Struct Repository 

pub struct Repository { /* private fields */ }

Implementations

impl Repository

pub fn add<P: AsRef<Path>>(&self, paths: &[P]) -> Result<()>

Add specific files or paths to the staging area.

Arguments

• paths - The file paths to add to the staging area

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/merge_operations.rs (line 52)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/error_handling.rs (line 108)

fn demonstrate_file_operation_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("File Operation Error Scenarios:\n");

    // Set up a valid repository first
    let repo = Repository::init(repo_path, false)?;

    // Create some test files
    fs::write(repo_path.join("test.txt"), "Test content")?;
    repo.add(&["test.txt"])?;
    repo.commit("Initial commit")?;

    // 1. Adding non-existent files
    println!("1. Attempting to add non-existent files:");
    match repo.add(&["does_not_exist.txt", "also_missing.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git add failed because files don't exist");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Mixed valid and invalid files
    println!("\n2. Adding mix of valid and invalid files:");
    fs::write(repo_path.join("valid.txt"), "Valid file")?;

    match repo.add(&["valid.txt", "invalid.txt"]) {
        Ok(_) => {
            println!("   Partially succeeded - some Git versions allow this");
            // Check what actually got staged
            let status = repo.status()?;
            println!("   {} files staged despite error", status.entries.len());
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Entire add operation failed due to invalid file");

            // Try recovery: add valid files individually
            println!("   Recovery: Adding valid files individually...");
            match repo.add(&["valid.txt"]) {
                Ok(_) => println!("      Successfully added valid.txt"),
                Err(e) => println!("      Recovery failed: {:?}", e),
            }
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate Git command related errors
fn demonstrate_git_command_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Git Command Error Scenarios:\n");

    let repo = Repository::open(repo_path)?;

    // 1. Empty commit (no staged changes)
    println!("1. Attempting commit with no staged changes:");
    match repo.commit("Empty commit attempt") {
        Ok(hash) => {
            println!("   Unexpectedly succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commits");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git requires changes to commit (normal behavior)");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Commit with problematic message
    println!("\n2. Testing commit message edge cases:");

    // Stage a file for testing
    fs::write(
        repo_path.join("commit_test.txt"),
        "Content for commit testing",
    )?;
    repo.add(&["commit_test.txt"])?;

    // Very long commit message
    let very_long_message = "A ".repeat(1000) + "very long commit message";
    match repo.commit(&very_long_message) {
        Ok(hash) => {
            println!("   Long commit message succeeded: {}", hash.short());
            println!("   Git handled the long message fine");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   Long commit message failed: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError with long message: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error recovery patterns
fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error propagation strategies
fn demonstrate_error_propagation_strategies(base_path: &std::path::Path) -> Result<()> {
    println!("Error Propagation Strategies:\n");

    // Strategy 1: Early return with ?
    println!("1. Early Return Strategy (using ?):");
    match workflow_with_early_return(base_path) {
        Ok(message) => println!("      Workflow completed: {}", message),
        Err(e) => println!("      Workflow failed early: {:?}", e),
    }

    // Strategy 2: Collect all errors
    println!("\n2. Error Collection Strategy:");
    let results = workflow_with_error_collection(base_path);

    let successful = results.iter().filter(|r| r.is_ok()).count();
    let failed = results.iter().filter(|r| r.is_err()).count();

    println!(
        "      Operations: {} succeeded, {} failed",
        successful, failed
    );

    for (i, result) in results.iter().enumerate() {
        match result {
            Ok(msg) => println!("         Step {}: {}", i + 1, msg),
            Err(e) => println!("         Step {}: {:?}", i + 1, e),
        }
    }

    // Strategy 3: Error context enrichment
    println!("\n3. Error Context Strategy:");
    match workflow_with_context(base_path) {
        Ok(message) => println!("      Contextual workflow: {}", message),
        Err(e) => println!("      Contextual workflow failed: {:?}", e),
    }

    println!();
    Ok(())
}

/// Workflow that returns early on first error
fn workflow_with_early_return(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("early_return_test");

    // This will propagate any error immediately
    let repo = Repository::init(&repo_path, false)?;

    fs::write(repo_path.join("file1.txt"), "Content 1")?;
    repo.add(&["file1.txt"])?;

    let hash = repo.commit("Early return workflow commit")?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Completed with commit {}", hash.short()))
}

/// Workflow that collects all errors instead of failing fast
fn workflow_with_error_collection(base_path: &std::path::Path) -> Vec<Result<String>> {
    let repo_path = base_path.join("error_collection_test");
    let mut results = Vec::new();

    // Step 1: Initialize repo
    results.push(Repository::init(&repo_path, false).map(|_| "Repository initialized".to_string()));

    // Step 2: Add files (some may fail)
    let files_to_create = ["good.txt", "another_good.txt"];

    for file in &files_to_create {
        results.push(
            fs::write(repo_path.join(file), "Content")
                .map_err(GitError::from)
                .map(|_| format!("Created {}", file)),
        );
    }

    // Step 3: Try to add files (continue even if repo init failed)
    if let Ok(repo) = Repository::open(&repo_path) {
        results.push(
            repo.add(&files_to_create)
                .map(|_| "Files added to staging".to_string()),
        );

        results.push(
            repo.commit("Error collection workflow")
                .map(|hash| format!("Committed: {}", hash.short())),
        );
    } else {
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for adding files".to_string(),
        )));
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for commit".to_string(),
        )));
    }

    // Cleanup (don't add to results as it's not part of main workflow)
    let _ = fs::remove_dir_all(&repo_path);

    results
}

/// Workflow with enhanced error context
fn workflow_with_context(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("context_test");

    // Add context to errors
    let repo = Repository::init(&repo_path, false).inspect_err(|_e| {
        eprintln!(
            "Context: Failed to initialize repository at {}",
            repo_path.display()
        );
    })?;

    // Create file with context
    fs::write(repo_path.join("context_file.txt"), "Content with context").map_err(|e| {
        eprintln!("Context: Failed to create context_file.txt");
        GitError::from(e)
    })?;

    // Add with context
    repo.add(&["context_file.txt"]).inspect_err(|_e| {
        eprintln!("Context: Failed to stage context_file.txt");
    })?;

    // Commit with context
    let hash = repo.commit("Context workflow commit").inspect_err(|_e| {
        eprintln!("Context: Failed to create commit");
    })?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Context workflow completed: {}", hash.short()))
}

examples/reset_operations.rs (line 52)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

fn demonstrate_file_resets(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating File-Specific Resets ---\n");

    // Create some files and stage them
    println!("1. Creating and staging multiple files...");

    let file_a = temp_dir.join("fileA.txt");
    let file_b = temp_dir.join("fileB.txt");

    fs::write(&file_a, "Content A")?;
    fs::write(&file_b, "Content B")?;

    repo.add(&["fileA.txt", "fileB.txt"])?;
    println!("   Staged fileA.txt and fileB.txt");

    show_repo_state(repo)?;

    // Reset a single file (using existing reset_file from files.rs)
    println!("\n2. Resetting single file (fileA.txt)...");
    repo.reset_file("fileA.txt")?;

    println!("   After resetting fileA.txt:");
    show_repo_state(repo)?;
    println!("   Note: fileA.txt is unstaged, fileB.txt remains staged");

    // Demonstrate HEAD reset (unstage all changes)
    println!("\n3. Performing mixed reset to HEAD (unstage all)...");
    repo.reset_mixed("HEAD")?;

    println!("   After reset HEAD:");
    show_repo_state(repo)?;
    println!("   Note: All staged changes are now unstaged");

    Ok(())
}

examples/basic_usage.rs (line 79)

fn main() -> Result<()> {
    println!("Rustic Git - Basic Usage Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_basic_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Create some example files
    println!("Creating example files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello from rustic-git example!");
}
"#,
    )?;

    fs::write(
        repo_path.join("src/lib.rs"),
        "// Library code goes here\npub fn hello() -> &'static str {\n    \"Hello, World!\"\n}\n",
    )?;

    println!("Created 3 files: README.md, src/main.rs, src/lib.rs\n");

    // Check repository status
    println!("Checking repository status...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("   Repository is clean (no changes)");
    } else {
        println!("   Repository has changes:");
        println!("   Unstaged files: {}", status.unstaged_files().count());
        println!("   Untracked files: {}", status.untracked_entries().count());

        // Show untracked files
        for entry in status.untracked_entries() {
            println!("      - {}", entry.path.display());
        }
    }
    println!();

    // Stage specific files first
    println!("Staging files...");

    // Stage README.md first
    repo.add(&["README.md"])?;
    println!("Staged README.md");

    // Stage all remaining files
    repo.add_all()?;
    println!("Staged all remaining files");

    // Check status after staging
    let status_after_staging = repo.status()?;
    println!("\nStatus after staging:");
    if status_after_staging.is_clean() {
        println!("   Repository is clean (all changes staged)");
    } else {
        println!(
            "   Files staged for commit: {}",
            status_after_staging.entries.len()
        );
        for entry in &status_after_staging.entries {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }
    println!();

    // Create a commit
    println!("Creating commit...");
    let hash = repo.commit("Initial commit: Add project structure and basic files")?;

    println!("Commit created successfully!");
    println!("   Full hash: {}", hash);
    println!("   Short hash: {}", hash.short());
    println!();

    // Verify final status
    println!("Final repository status:");
    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("   Repository is clean - all changes committed!");
    } else {
        println!("   Repository still has uncommitted changes");
    }
    println!();

    // Clean up
    println!("Cleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Example completed successfully!");

    Ok(())
}

examples/branch_operations.rs (line 18)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

examples/config_operations.rs (line 87)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Configuration Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_config_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;

    // ==================== USER CONFIGURATION ====================

    println!("\n[CONFIG] Configuring git user settings...");

    // Set user configuration (convenience method)
    repo.config()
        .set_user("Alice Developer", "alice@example.com")?;
    println!("Set user configuration");

    // Verify user configuration
    let (name, email) = repo.config().get_user()?;
    println!("Current user: {} <{}>", name, email);

    // ==================== GENERAL CONFIGURATION ====================

    println!("\n[CONFIG] Setting repository configuration values...");

    // Set various git configuration values
    repo.config().set("core.autocrlf", "false")?;
    repo.config().set("core.ignorecase", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "simple")?;
    repo.config().set("branch.autosetupmerge", "always")?;

    println!("Set core configuration values");

    // Get and display configuration values
    println!("\n[CONFIG] Current repository configuration:");

    let configs = [
        "core.autocrlf",
        "core.ignorecase",
        "pull.rebase",
        "push.default",
        "branch.autosetupmerge",
    ];

    for config_key in &configs {
        match repo.config().get(config_key) {
            Ok(value) => println!("  {} = {}", config_key, value),
            Err(_) => println!("  {} = <not set>", config_key),
        }
    }

    // ==================== CONFIGURATION WITH COMMITS ====================

    println!("\n[COMMIT] Testing configuration with commit operations...");

    // Create a test file
    let test_file_path = repo_path.join("test.txt");
    fs::write(
        &test_file_path,
        "Hello from rustic-git configuration example!",
    )?;
    println!("Created test file: test.txt");

    // Stage the file
    repo.add(&["test.txt"])?;
    println!("Staged test.txt");

    // Create a commit (this will use our configured user)
    let commit_hash = repo.commit("Add test file with configuration example")?;
    println!("Created commit: {}", commit_hash.short());

    // ==================== CONFIGURATION MODIFICATION ====================

    println!("\n[UPDATE] Modifying configuration values...");

    // Change some configuration values
    repo.config().set("core.autocrlf", "true")?;
    repo.config()
        .set("user.email", "alice.developer@newcompany.com")?;

    println!("Updated configuration values");

    // Display updated values
    let autocrlf = repo.config().get("core.autocrlf")?;
    let (updated_name, updated_email) = repo.config().get_user()?;

    println!("Updated configuration:");
    println!("  core.autocrlf = {}", autocrlf);
    println!("  user: {} <{}>", updated_name, updated_email);

    // ==================== CONFIGURATION REMOVAL ====================

    println!("\n[REMOVE] Removing configuration values...");

    // Remove a configuration value
    repo.config().unset("branch.autosetupmerge")?;
    println!("Removed branch.autosetupmerge");

    // Try to get the removed value (should fail)
    match repo.config().get("branch.autosetupmerge") {
        Ok(value) => println!("Unexpected: branch.autosetupmerge = {}", value),
        Err(_) => println!("Confirmed: branch.autosetupmerge is not set"),
    }

    // ==================== ADVANCED CONFIGURATION ====================

    println!("\n[ADVANCED] Setting advanced configuration...");

    // Set some advanced git configuration
    repo.config().set("diff.tool", "vimdiff")?;
    repo.config().set("merge.tool", "vimdiff")?;
    repo.config().set("alias.st", "status")?;
    repo.config().set("alias.co", "checkout")?;
    repo.config().set("alias.br", "branch")?;
    repo.config().set("alias.ci", "commit")?;

    println!("Set advanced configuration (diff/merge tools and aliases)");

    // Display all custom configuration
    println!("\n[SUMMARY] Complete repository configuration summary:");

    let all_configs = [
        ("User", vec![("user.name", ""), ("user.email", "")]),
        ("Core", vec![("core.autocrlf", ""), ("core.ignorecase", "")]),
        ("Workflow", vec![("pull.rebase", ""), ("push.default", "")]),
        ("Tools", vec![("diff.tool", ""), ("merge.tool", "")]),
        (
            "Aliases",
            vec![
                ("alias.st", ""),
                ("alias.co", ""),
                ("alias.br", ""),
                ("alias.ci", ""),
            ],
        ),
    ];

    for (category, configs) in &all_configs {
        println!("\n  {}:", category);
        for (key, _) in configs {
            match repo.config().get(key) {
                Ok(value) => println!("    {} = {}", key, value),
                Err(_) => println!("    {} = <not set>", key),
            }
        }
    }

    // ==================== PRACTICAL EXAMPLE ====================

    println!("\n[TEAM] Practical example: Setting up repository for a team...");

    // Configure repository for team development
    repo.config().set("user.name", "Team Member")?;
    repo.config().set("user.email", "team@company.com")?;
    repo.config().set("core.autocrlf", "input")?;
    repo.config().set("core.safecrlf", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "current")?;
    repo.config().set("init.defaultBranch", "main")?;

    println!("Configured repository for team development");

    // Create another commit with the team configuration
    fs::write(
        repo_path.join("team.md"),
        "# Team Development\n\nThis repository is configured for team development.",
    )?;
    repo.add(&["team.md"])?;
    let team_commit = repo.commit("Add team development documentation")?;

    println!("Created team commit: {}", team_commit.short());

    // Final verification
    let (final_name, final_email) = repo.config().get_user()?;
    println!("\n[FINAL] Final repository configuration:");
    println!("  User: {} <{}>", final_name, final_email);
    println!("  Repository configured for team development workflow");

    // ==================== CLEANUP ====================

    println!("\n[CLEANUP] Cleaning up...");
    fs::remove_dir_all(&repo_path).expect("Failed to clean up example");
    println!("Example completed successfully!");

    Ok(())
}

Additional examples can be found in:

• examples/status_checking.rs
• examples/staging_operations.rs
• examples/diff_operations.rs
• examples/commit_workflows.rs
• examples/tag_operations.rs
• examples/remote_operations.rs
• examples/commit_history.rs
• examples/stash_operations.rs
• examples/file_lifecycle_operations.rs

pub fn add_all(&self) -> Result<()>

Add all changes to the staging area (equivalent to git add .).

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/basic_usage.rs (line 83)

fn main() -> Result<()> {
    println!("Rustic Git - Basic Usage Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_basic_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Create some example files
    println!("Creating example files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello from rustic-git example!");
}
"#,
    )?;

    fs::write(
        repo_path.join("src/lib.rs"),
        "// Library code goes here\npub fn hello() -> &'static str {\n    \"Hello, World!\"\n}\n",
    )?;

    println!("Created 3 files: README.md, src/main.rs, src/lib.rs\n");

    // Check repository status
    println!("Checking repository status...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("   Repository is clean (no changes)");
    } else {
        println!("   Repository has changes:");
        println!("   Unstaged files: {}", status.unstaged_files().count());
        println!("   Untracked files: {}", status.untracked_entries().count());

        // Show untracked files
        for entry in status.untracked_entries() {
            println!("      - {}", entry.path.display());
        }
    }
    println!();

    // Stage specific files first
    println!("Staging files...");

    // Stage README.md first
    repo.add(&["README.md"])?;
    println!("Staged README.md");

    // Stage all remaining files
    repo.add_all()?;
    println!("Staged all remaining files");

    // Check status after staging
    let status_after_staging = repo.status()?;
    println!("\nStatus after staging:");
    if status_after_staging.is_clean() {
        println!("   Repository is clean (all changes staged)");
    } else {
        println!(
            "   Files staged for commit: {}",
            status_after_staging.entries.len()
        );
        for entry in &status_after_staging.entries {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }
    println!();

    // Create a commit
    println!("Creating commit...");
    let hash = repo.commit("Initial commit: Add project structure and basic files")?;

    println!("Commit created successfully!");
    println!("   Full hash: {}", hash);
    println!("   Short hash: {}", hash.short());
    println!();

    // Verify final status
    println!("Final repository status:");
    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("   Repository is clean - all changes committed!");
    } else {
        println!("   Repository still has uncommitted changes");
    }
    println!();

    // Clean up
    println!("Cleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Example completed successfully!");

    Ok(())
}

examples/error_handling.rs (line 225)

fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

examples/staging_operations.rs (line 46)

fn main() -> Result<()> {
    println!("Rustic Git - Staging Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_staging_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    // Initialize repository and create initial commit
    println!("Setting up repository with initial files...");
    let repo = Repository::init(&repo_path, false)?;

    // Create initial files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;

    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nOriginal content",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() { println!(\"v1\"); }",
    )?;
    fs::write(
        repo_path.join("src/lib.rs"),
        "pub fn version() -> &'static str { \"1.0\" }",
    )?;

    // Create initial commit so we can demonstrate staging tracked file changes
    repo.add_all()?;
    let _initial_hash = repo.commit("Initial commit with basic files")?;
    println!("Created initial repository with 3 files\n");

    println!("=== Staging Specific Files with add() ===\n");

    // Create some new files and modify existing ones
    println!("Creating new files and modifying existing ones...");
    fs::write(repo_path.join("new_file1.txt"), "New file 1 content")?;
    fs::write(repo_path.join("new_file2.txt"), "New file 2 content")?;
    fs::write(repo_path.join("docs/guide.md"), "# User Guide")?;

    // Modify existing files
    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nUpdated content!",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() { println!(\"v2 - updated!\"); }",
    )?;

    println!("Created 3 new files and modified 2 existing files");

    // Show status before staging
    println!("\nStatus before staging:");
    let status_before = repo.status()?;
    display_status_breakdown(&status_before);

    // Stage specific files using add()
    println!("\nUsing add() to stage specific files:");

    // Stage just the README.md
    repo.add(&["README.md"])?;
    println!("   Staged README.md");

    let status_after_readme = repo.status()?;
    display_status_changes(
        &status_before,
        &status_after_readme,
        "after staging README.md",
    );

    // Stage multiple specific files
    repo.add(&["new_file1.txt", "src/main.rs"])?;
    println!("   Staged new_file1.txt and src/main.rs");

    let status_after_multiple = repo.status()?;
    display_status_changes(
        &status_after_readme,
        &status_after_multiple,
        "after staging multiple files",
    );

    // Stage using Path objects (alternative syntax)
    use std::path::Path as StdPath;
    repo.add(&[StdPath::new("docs/guide.md")])?;
    println!("   Staged docs/guide.md using Path object");

    let status_after_path = repo.status()?;
    display_status_changes(
        &status_after_multiple,
        &status_after_path,
        "after staging with Path object",
    );

    println!();

    println!("=== Staging All Changes with add_all() ===\n");

    // Create more files to demonstrate add_all()
    println!("Creating additional files for add_all() demo...");
    fs::write(
        repo_path.join("config.toml"),
        "[package]\nname = \"example\"",
    )?;
    fs::write(repo_path.join("src/utils.rs"), "pub fn helper() {}")?;
    fs::create_dir_all(repo_path.join("tests"))?;
    fs::write(
        repo_path.join("tests/integration.rs"),
        "#[test]\nfn test_basic() {}",
    )?;

    println!("Created 3 more files");

    let status_before_add_all = repo.status()?;
    println!("\nStatus before add_all():");
    display_status_breakdown(&status_before_add_all);

    // Use add_all() to stage everything remaining
    println!("\nUsing add_all() to stage all remaining changes:");
    repo.add_all()?;
    println!("   Staged all changes with add_all()");

    let status_after_add_all = repo.status()?;
    display_status_changes(
        &status_before_add_all,
        &status_after_add_all,
        "after add_all()",
    );

    // Create a commit to set up for add_update() demo
    let _commit_hash = repo.commit("Add all new files and modifications")?;
    println!("   Committed all staged changes\n");

    println!("=== Staging Tracked Changes with add_update() ===\n");

    // Create new untracked files and modify existing tracked files
    println!("Setting up files for add_update() demonstration...");

    // Create new untracked files (these should NOT be staged by add_update)
    fs::write(repo_path.join("untracked1.txt"), "This is untracked")?;
    fs::write(repo_path.join("untracked2.txt"), "Another untracked file")?;

    // Modify existing tracked files (these SHOULD be staged by add_update)
    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nContent updated again for add_update demo!",
    )?;
    fs::write(
        repo_path.join("src/lib.rs"),
        "pub fn version() -> &'static str { \"2.0\" }",
    )?;
    fs::write(
        repo_path.join("config.toml"),
        "[package]\nname = \"example\"\nversion = \"0.2.0\"",
    )?;

    println!("Created 2 untracked files and modified 3 tracked files");

    let status_before_add_update = repo.status()?;
    println!("\nStatus before add_update():");
    display_status_breakdown(&status_before_add_update);

    // Use add_update() to stage only tracked file changes
    println!("\nUsing add_update() to stage only tracked file modifications:");
    repo.add_update()?;
    println!("   Used add_update() - should stage modified tracked files only");

    let status_after_add_update = repo.status()?;
    display_status_changes(
        &status_before_add_update,
        &status_after_add_update,
        "after add_update()",
    );

    // Verify that untracked files are still untracked
    let remaining_untracked: Vec<_> = status_after_add_update.untracked_entries().collect();
    if !remaining_untracked.is_empty() {
        println!("   Untracked files remain untracked (as expected):");
        for entry in remaining_untracked {
            println!("      - {}", entry.path.display());
        }
    }

    println!();

    println!("=== Error Handling in Staging Operations ===\n");

    // Demonstrate error handling
    println!("Testing error conditions:");

    // Try to add non-existent files
    match repo.add(&["nonexistent_file.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded adding non-existent file"),
        Err(e) => println!("   Expected error for non-existent file: {:?}", e),
    }

    // Try to add empty array (should succeed but do nothing)
    match repo.add(&[] as &[&str]) {
        Ok(_) => println!("   Empty add() succeeded (no-op)"),
        Err(e) => println!("   Empty add() failed: {:?}", e),
    }

    println!();

    println!("=== Final Repository State ===\n");

    let final_status = repo.status()?;
    println!("Final repository summary:");
    display_status_breakdown(&final_status);

    if final_status.has_changes() {
        let staged_count = final_status.staged_files().count();
        let untracked_count = final_status.untracked_entries().count();

        println!("\nRepository state:");
        println!("   {} files staged and ready to commit", staged_count);
        println!("   {} untracked files not yet added", untracked_count);

        if staged_count > 0 {
            println!("\n   You could now commit with: repo.commit(\"Your message\")?");
        }
    }

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Staging operations example completed!");

    Ok(())
}

examples/diff_operations.rs (line 50)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

examples/commit_workflows.rs (line 62)

fn main() -> Result<()> {
    println!("Rustic Git - Commit Workflows Example\n");

    let repo_path = env::temp_dir().join("rustic_git_commit_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    // Initialize repository
    println!("Setting up repository for commit demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized\n");

    println!("=== Basic Commit Operations ===\n");

    // Create initial files
    println!("Creating initial project files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# Commit Demo Project\n\nThis project demonstrates commit workflows with rustic-git.\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello, Commit Demo!");
}
"#,
    )?;

    fs::write(
        repo_path.join("Cargo.toml"),
        r#"[package]
name = "commit-demo"
version = "0.1.0"
edition = "2021"
"#,
    )?;

    println!("Created README.md, src/main.rs, and Cargo.toml");

    // Stage and commit with basic commit()
    println!("\nStaging files for first commit...");
    repo.add_all()?;

    println!("Creating first commit with basic commit() method:");
    let first_hash = repo.commit("Initial commit: Add project structure")?;

    println!("First commit created!");
    display_hash_info(&first_hash, "First commit");
    println!();

    println!("=== Hash Type Demonstrations ===\n");

    println!("Hash type methods and usage:");

    // Demonstrate different ways to work with Hash
    let hash_as_string: String = first_hash.to_string();
    let hash_as_str: &str = first_hash.as_str();
    let short_hash: &str = first_hash.short();

    println!("   Hash conversions:");
    println!("      as_str(): '{}'", hash_as_str);
    println!("      short(): '{}'", short_hash);
    println!("      to_string(): '{}'", hash_as_string);
    println!("      Display: '{}'", first_hash);

    // Demonstrate Hash equality and cloning
    let cloned_hash = first_hash.clone();
    println!("\n   Hash operations:");
    println!("      Original == Clone: {}", first_hash == cloned_hash);
    println!(
        "      Hash length: {} characters",
        first_hash.as_str().len()
    );
    println!(
        "      Short hash length: {} characters",
        first_hash.short().len()
    );

    // Create Hash from different sources for demonstration
    let hash_from_string: Hash = "1234567890abcdef".to_string().into();
    let hash_from_str: Hash = "fedcba0987654321".into();

    println!("      Hash from String: {}", hash_from_string.short());
    println!("      Hash from &str: {}", hash_from_str.short());
    println!();

    println!("=== Commits with Custom Authors ===\n");

    // Create more files to commit with custom author
    println!("Adding features for custom author commit...");
    fs::create_dir_all(repo_path.join("tests"))?;

    fs::write(
        repo_path.join("src/lib.rs"),
        r#"//! Commit demo library

pub fn greet(name: &str) -> String {
    format!("Hello, {}! This is a commit demo.", name)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_greet() {
        assert_eq!(greet("Alice"), "Hello, Alice! This is a commit demo.");
    }
}
"#,
    )?;

    fs::write(
        repo_path.join("tests/integration_test.rs"),
        r#"use commit_demo::greet;

#[test]
fn test_integration() {
    let result = greet("Integration");
    assert!(result.contains("Integration"));
    assert!(result.contains("commit demo"));
}
"#,
    )?;

    println!("Created src/lib.rs and tests/integration_test.rs");

    // Stage and commit with custom author
    repo.add_all()?;
    println!("\nCreating commit with custom author:");
    let second_hash = repo.commit_with_author(
        "Add library code and tests\n\n- Implement greet function with proper documentation\n- Add unit tests and integration tests\n- Prepare for version 0.2.0 release",
        "Jane Developer <jane.dev@example.com>"
    )?;

    println!("Commit with custom author created!");
    display_hash_info(&second_hash, "Second commit (custom author)");
    println!();

    println!("=== Multiple Commit Workflow ===\n");

    // Demonstrate a series of commits
    let mut commit_hashes = vec![first_hash, second_hash];

    // Commit 3: Update version
    println!("Step 1: Update version information...");
    fs::write(
        repo_path.join("Cargo.toml"),
        r#"[package]
name = "commit-demo"
version = "0.2.0"
edition = "2021"
description = "A demo project for commit workflows"
"#,
    )?;

    repo.add(&["Cargo.toml"])?;
    let third_hash = repo.commit("Bump version to 0.2.0 and add description")?;
    commit_hashes.push(third_hash);

    // Commit 4: Add documentation
    println!("Step 2: Add documentation...");
    fs::write(
        repo_path.join("CHANGELOG.md"),
        r#"# Changelog

## [0.2.0] - 2024-01-01

### Added
- Library functionality with greet function
- Comprehensive test suite
- Project documentation

## [0.1.0] - 2024-01-01

### Added
- Initial project structure
- Basic Cargo configuration
"#,
    )?;

    repo.add(&["CHANGELOG.md"])?;
    let fourth_hash = repo.commit_with_author(
        "docs: Add CHANGELOG with version history",
        "Doc Writer <docs@example.com>",
    )?;
    commit_hashes.push(fourth_hash);

    // Commit 5: Final polish
    println!("Step 3: Final polish...");
    fs::write(
        repo_path.join("README.md"),
        r#"# Commit Demo Project

This project demonstrates commit workflows with rustic-git.

## Features

- Clean, type-safe Git operations
- Comprehensive commit history
- Multiple author support
- Hash management utilities

## Usage

```rust
use commit_demo::greet;

fn main() {
    println!("{}", greet("World"));
}
```

## Version

Current version: 0.2.0

See CHANGELOG.md for version history.
"#,
    )?;

    repo.add(&["README.md"])?;
    let fifth_hash = repo.commit("docs: Enhance README with usage examples and features")?;
    commit_hashes.push(fifth_hash);

    println!("\nComplete commit history created!");

    // Display all commits
    println!("\n=== Commit History Summary ===\n");

    for (i, hash) in commit_hashes.iter().enumerate() {
        println!("{}. Commit {}", i + 1, i + 1);
        display_hash_info(hash, &format!("Commit {}", i + 1));
        println!();
    }

    // Compare hashes
    println!("Hash comparisons:");
    println!(
        "   First commit == Last commit: {}",
        commit_hashes[0] == commit_hashes[4]
    );
    println!("   All hashes unique: {}", all_unique(&commit_hashes));

    // Show short hashes for all commits
    println!("\nAll commit short hashes:");
    for (i, hash) in commit_hashes.iter().enumerate() {
        println!("   {}: {}", i + 1, hash.short());
    }
    println!();

    println!("=== Error Handling for Commits ===\n");

    // Try to commit with nothing staged (should fail)
    println!("Testing commit with no staged changes:");
    match repo.commit("This should fail - no changes") {
        Ok(_hash) => println!("   Unexpectedly succeeded with empty commit"),
        Err(e) => {
            println!("   Expected error for empty commit: {:?}", e);
            println!("   This is normal behavior - Git requires changes to commit");
        }
    }

    // Try commit with custom author but no changes (should also fail)
    println!("\nTesting custom author commit with no changes:");
    match repo.commit_with_author("This should also fail", "Test Author <test@example.com>") {
        Ok(_hash) => println!("   Unexpectedly succeeded with empty custom author commit"),
        Err(e) => {
            println!(
                "   Expected error for empty commit with custom author: {:?}",
                e
            );
        }
    }

    // Test commit with empty message (Git might handle this differently)
    println!("\nTesting commit with empty message:");

    // Create a change to commit
    fs::write(repo_path.join("temp_for_empty_message.txt"), "temp content")?;
    repo.add(&["temp_for_empty_message.txt"])?;

    match repo.commit("") {
        Ok(hash) => {
            println!("   Commit with empty message succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commit messages");
        }
        Err(e) => {
            println!("   Empty commit message rejected: {:?}", e);
        }
    }

    println!();

    println!("=== Final Repository State ===\n");

    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("Repository is clean - all changes committed!");
    } else {
        println!(
            "Repository has {} uncommitted changes",
            final_status.entries.len()
        );
    }

    println!("\nWorkflow summary:");
    println!("   Total commits created: {}", commit_hashes.len());
    println!("   Hash examples demonstrated: [OK]");
    println!("   Custom author commits: [OK]");
    println!("   Error handling tested: [OK]");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Commit workflows example completed!");

    Ok(())
}

pub fn add_update(&self) -> Result<()>

Add all tracked files that have been modified (equivalent to git add -u).

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/staging_operations.rs (line 182)

fn main() -> Result<()> {
    println!("Rustic Git - Staging Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_staging_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    // Initialize repository and create initial commit
    println!("Setting up repository with initial files...");
    let repo = Repository::init(&repo_path, false)?;

    // Create initial files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;

    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nOriginal content",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() { println!(\"v1\"); }",
    )?;
    fs::write(
        repo_path.join("src/lib.rs"),
        "pub fn version() -> &'static str { \"1.0\" }",
    )?;

    // Create initial commit so we can demonstrate staging tracked file changes
    repo.add_all()?;
    let _initial_hash = repo.commit("Initial commit with basic files")?;
    println!("Created initial repository with 3 files\n");

    println!("=== Staging Specific Files with add() ===\n");

    // Create some new files and modify existing ones
    println!("Creating new files and modifying existing ones...");
    fs::write(repo_path.join("new_file1.txt"), "New file 1 content")?;
    fs::write(repo_path.join("new_file2.txt"), "New file 2 content")?;
    fs::write(repo_path.join("docs/guide.md"), "# User Guide")?;

    // Modify existing files
    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nUpdated content!",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() { println!(\"v2 - updated!\"); }",
    )?;

    println!("Created 3 new files and modified 2 existing files");

    // Show status before staging
    println!("\nStatus before staging:");
    let status_before = repo.status()?;
    display_status_breakdown(&status_before);

    // Stage specific files using add()
    println!("\nUsing add() to stage specific files:");

    // Stage just the README.md
    repo.add(&["README.md"])?;
    println!("   Staged README.md");

    let status_after_readme = repo.status()?;
    display_status_changes(
        &status_before,
        &status_after_readme,
        "after staging README.md",
    );

    // Stage multiple specific files
    repo.add(&["new_file1.txt", "src/main.rs"])?;
    println!("   Staged new_file1.txt and src/main.rs");

    let status_after_multiple = repo.status()?;
    display_status_changes(
        &status_after_readme,
        &status_after_multiple,
        "after staging multiple files",
    );

    // Stage using Path objects (alternative syntax)
    use std::path::Path as StdPath;
    repo.add(&[StdPath::new("docs/guide.md")])?;
    println!("   Staged docs/guide.md using Path object");

    let status_after_path = repo.status()?;
    display_status_changes(
        &status_after_multiple,
        &status_after_path,
        "after staging with Path object",
    );

    println!();

    println!("=== Staging All Changes with add_all() ===\n");

    // Create more files to demonstrate add_all()
    println!("Creating additional files for add_all() demo...");
    fs::write(
        repo_path.join("config.toml"),
        "[package]\nname = \"example\"",
    )?;
    fs::write(repo_path.join("src/utils.rs"), "pub fn helper() {}")?;
    fs::create_dir_all(repo_path.join("tests"))?;
    fs::write(
        repo_path.join("tests/integration.rs"),
        "#[test]\nfn test_basic() {}",
    )?;

    println!("Created 3 more files");

    let status_before_add_all = repo.status()?;
    println!("\nStatus before add_all():");
    display_status_breakdown(&status_before_add_all);

    // Use add_all() to stage everything remaining
    println!("\nUsing add_all() to stage all remaining changes:");
    repo.add_all()?;
    println!("   Staged all changes with add_all()");

    let status_after_add_all = repo.status()?;
    display_status_changes(
        &status_before_add_all,
        &status_after_add_all,
        "after add_all()",
    );

    // Create a commit to set up for add_update() demo
    let _commit_hash = repo.commit("Add all new files and modifications")?;
    println!("   Committed all staged changes\n");

    println!("=== Staging Tracked Changes with add_update() ===\n");

    // Create new untracked files and modify existing tracked files
    println!("Setting up files for add_update() demonstration...");

    // Create new untracked files (these should NOT be staged by add_update)
    fs::write(repo_path.join("untracked1.txt"), "This is untracked")?;
    fs::write(repo_path.join("untracked2.txt"), "Another untracked file")?;

    // Modify existing tracked files (these SHOULD be staged by add_update)
    fs::write(
        repo_path.join("README.md"),
        "# Staging Demo\nContent updated again for add_update demo!",
    )?;
    fs::write(
        repo_path.join("src/lib.rs"),
        "pub fn version() -> &'static str { \"2.0\" }",
    )?;
    fs::write(
        repo_path.join("config.toml"),
        "[package]\nname = \"example\"\nversion = \"0.2.0\"",
    )?;

    println!("Created 2 untracked files and modified 3 tracked files");

    let status_before_add_update = repo.status()?;
    println!("\nStatus before add_update():");
    display_status_breakdown(&status_before_add_update);

    // Use add_update() to stage only tracked file changes
    println!("\nUsing add_update() to stage only tracked file modifications:");
    repo.add_update()?;
    println!("   Used add_update() - should stage modified tracked files only");

    let status_after_add_update = repo.status()?;
    display_status_changes(
        &status_before_add_update,
        &status_after_add_update,
        "after add_update()",
    );

    // Verify that untracked files are still untracked
    let remaining_untracked: Vec<_> = status_after_add_update.untracked_entries().collect();
    if !remaining_untracked.is_empty() {
        println!("   Untracked files remain untracked (as expected):");
        for entry in remaining_untracked {
            println!("      - {}", entry.path.display());
        }
    }

    println!();

    println!("=== Error Handling in Staging Operations ===\n");

    // Demonstrate error handling
    println!("Testing error conditions:");

    // Try to add non-existent files
    match repo.add(&["nonexistent_file.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded adding non-existent file"),
        Err(e) => println!("   Expected error for non-existent file: {:?}", e),
    }

    // Try to add empty array (should succeed but do nothing)
    match repo.add(&[] as &[&str]) {
        Ok(_) => println!("   Empty add() succeeded (no-op)"),
        Err(e) => println!("   Empty add() failed: {:?}", e),
    }

    println!();

    println!("=== Final Repository State ===\n");

    let final_status = repo.status()?;
    println!("Final repository summary:");
    display_status_breakdown(&final_status);

    if final_status.has_changes() {
        let staged_count = final_status.staged_files().count();
        let untracked_count = final_status.untracked_entries().count();

        println!("\nRepository state:");
        println!("   {} files staged and ready to commit", staged_count);
        println!("   {} untracked files not yet added", untracked_count);

        if staged_count > 0 {
            println!("\n   You could now commit with: repo.commit(\"Your message\")?");
        }
    }

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Staging operations example completed!");

    Ok(())
}

impl Repository

pub fn branches(&self) -> Result<BranchList>

List all branches in the repository

Examples found in repository

examples/merge_operations.rs (line 68)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/branch_operations.rs (line 23)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn current_branch(&self) -> Result<Option<Branch>>

Get the current branch

Examples found in repository

examples/branch_operations.rs (line 30)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn create_branch( &self, name: &str, start_point: Option<&str>, ) -> Result<Branch>

Create a new branch

Examples found in repository

examples/branch_operations.rs (line 40)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn delete_branch(&self, branch: &Branch, force: bool) -> Result<()>

Delete a branch

Examples found in repository

examples/branch_operations.rs (line 129)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn checkout(&self, branch: &Branch) -> Result<()>

Switch to an existing branch

Examples found in repository

examples/merge_operations.rs (line 70)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/branch_operations.rs (line 75)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn checkout_new( &self, name: &str, start_point: Option<&str>, ) -> Result<Branch>

Create a new branch and switch to it

Examples found in repository

examples/merge_operations.rs (line 58)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/branch_operations.rs (line 55)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

impl Repository

pub fn commit(&self, message: &str) -> Result<Hash>

Create a commit with the given message.

Arguments

• message - The commit message

Returns

A Result containing the Hash of the new commit or a GitError.

Examples found in repository

examples/merge_operations.rs (line 53)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/error_handling.rs (line 109)

fn demonstrate_file_operation_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("File Operation Error Scenarios:\n");

    // Set up a valid repository first
    let repo = Repository::init(repo_path, false)?;

    // Create some test files
    fs::write(repo_path.join("test.txt"), "Test content")?;
    repo.add(&["test.txt"])?;
    repo.commit("Initial commit")?;

    // 1. Adding non-existent files
    println!("1. Attempting to add non-existent files:");
    match repo.add(&["does_not_exist.txt", "also_missing.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git add failed because files don't exist");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Mixed valid and invalid files
    println!("\n2. Adding mix of valid and invalid files:");
    fs::write(repo_path.join("valid.txt"), "Valid file")?;

    match repo.add(&["valid.txt", "invalid.txt"]) {
        Ok(_) => {
            println!("   Partially succeeded - some Git versions allow this");
            // Check what actually got staged
            let status = repo.status()?;
            println!("   {} files staged despite error", status.entries.len());
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Entire add operation failed due to invalid file");

            // Try recovery: add valid files individually
            println!("   Recovery: Adding valid files individually...");
            match repo.add(&["valid.txt"]) {
                Ok(_) => println!("      Successfully added valid.txt"),
                Err(e) => println!("      Recovery failed: {:?}", e),
            }
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate Git command related errors
fn demonstrate_git_command_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Git Command Error Scenarios:\n");

    let repo = Repository::open(repo_path)?;

    // 1. Empty commit (no staged changes)
    println!("1. Attempting commit with no staged changes:");
    match repo.commit("Empty commit attempt") {
        Ok(hash) => {
            println!("   Unexpectedly succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commits");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git requires changes to commit (normal behavior)");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Commit with problematic message
    println!("\n2. Testing commit message edge cases:");

    // Stage a file for testing
    fs::write(
        repo_path.join("commit_test.txt"),
        "Content for commit testing",
    )?;
    repo.add(&["commit_test.txt"])?;

    // Very long commit message
    let very_long_message = "A ".repeat(1000) + "very long commit message";
    match repo.commit(&very_long_message) {
        Ok(hash) => {
            println!("   Long commit message succeeded: {}", hash.short());
            println!("   Git handled the long message fine");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   Long commit message failed: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError with long message: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error recovery patterns
fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error propagation strategies
fn demonstrate_error_propagation_strategies(base_path: &std::path::Path) -> Result<()> {
    println!("Error Propagation Strategies:\n");

    // Strategy 1: Early return with ?
    println!("1. Early Return Strategy (using ?):");
    match workflow_with_early_return(base_path) {
        Ok(message) => println!("      Workflow completed: {}", message),
        Err(e) => println!("      Workflow failed early: {:?}", e),
    }

    // Strategy 2: Collect all errors
    println!("\n2. Error Collection Strategy:");
    let results = workflow_with_error_collection(base_path);

    let successful = results.iter().filter(|r| r.is_ok()).count();
    let failed = results.iter().filter(|r| r.is_err()).count();

    println!(
        "      Operations: {} succeeded, {} failed",
        successful, failed
    );

    for (i, result) in results.iter().enumerate() {
        match result {
            Ok(msg) => println!("         Step {}: {}", i + 1, msg),
            Err(e) => println!("         Step {}: {:?}", i + 1, e),
        }
    }

    // Strategy 3: Error context enrichment
    println!("\n3. Error Context Strategy:");
    match workflow_with_context(base_path) {
        Ok(message) => println!("      Contextual workflow: {}", message),
        Err(e) => println!("      Contextual workflow failed: {:?}", e),
    }

    println!();
    Ok(())
}

/// Workflow that returns early on first error
fn workflow_with_early_return(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("early_return_test");

    // This will propagate any error immediately
    let repo = Repository::init(&repo_path, false)?;

    fs::write(repo_path.join("file1.txt"), "Content 1")?;
    repo.add(&["file1.txt"])?;

    let hash = repo.commit("Early return workflow commit")?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Completed with commit {}", hash.short()))
}

/// Workflow that collects all errors instead of failing fast
fn workflow_with_error_collection(base_path: &std::path::Path) -> Vec<Result<String>> {
    let repo_path = base_path.join("error_collection_test");
    let mut results = Vec::new();

    // Step 1: Initialize repo
    results.push(Repository::init(&repo_path, false).map(|_| "Repository initialized".to_string()));

    // Step 2: Add files (some may fail)
    let files_to_create = ["good.txt", "another_good.txt"];

    for file in &files_to_create {
        results.push(
            fs::write(repo_path.join(file), "Content")
                .map_err(GitError::from)
                .map(|_| format!("Created {}", file)),
        );
    }

    // Step 3: Try to add files (continue even if repo init failed)
    if let Ok(repo) = Repository::open(&repo_path) {
        results.push(
            repo.add(&files_to_create)
                .map(|_| "Files added to staging".to_string()),
        );

        results.push(
            repo.commit("Error collection workflow")
                .map(|hash| format!("Committed: {}", hash.short())),
        );
    } else {
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for adding files".to_string(),
        )));
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for commit".to_string(),
        )));
    }

    // Cleanup (don't add to results as it's not part of main workflow)
    let _ = fs::remove_dir_all(&repo_path);

    results
}

/// Workflow with enhanced error context
fn workflow_with_context(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("context_test");

    // Add context to errors
    let repo = Repository::init(&repo_path, false).inspect_err(|_e| {
        eprintln!(
            "Context: Failed to initialize repository at {}",
            repo_path.display()
        );
    })?;

    // Create file with context
    fs::write(repo_path.join("context_file.txt"), "Content with context").map_err(|e| {
        eprintln!("Context: Failed to create context_file.txt");
        GitError::from(e)
    })?;

    // Add with context
    repo.add(&["context_file.txt"]).inspect_err(|_e| {
        eprintln!("Context: Failed to stage context_file.txt");
    })?;

    // Commit with context
    let hash = repo.commit("Context workflow commit").inspect_err(|_e| {
        eprintln!("Context: Failed to create commit");
    })?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Context workflow completed: {}", hash.short()))
}

examples/reset_operations.rs (line 53)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

examples/basic_usage.rs (line 109)

fn main() -> Result<()> {
    println!("Rustic Git - Basic Usage Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_basic_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Create some example files
    println!("Creating example files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello from rustic-git example!");
}
"#,
    )?;

    fs::write(
        repo_path.join("src/lib.rs"),
        "// Library code goes here\npub fn hello() -> &'static str {\n    \"Hello, World!\"\n}\n",
    )?;

    println!("Created 3 files: README.md, src/main.rs, src/lib.rs\n");

    // Check repository status
    println!("Checking repository status...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("   Repository is clean (no changes)");
    } else {
        println!("   Repository has changes:");
        println!("   Unstaged files: {}", status.unstaged_files().count());
        println!("   Untracked files: {}", status.untracked_entries().count());

        // Show untracked files
        for entry in status.untracked_entries() {
            println!("      - {}", entry.path.display());
        }
    }
    println!();

    // Stage specific files first
    println!("Staging files...");

    // Stage README.md first
    repo.add(&["README.md"])?;
    println!("Staged README.md");

    // Stage all remaining files
    repo.add_all()?;
    println!("Staged all remaining files");

    // Check status after staging
    let status_after_staging = repo.status()?;
    println!("\nStatus after staging:");
    if status_after_staging.is_clean() {
        println!("   Repository is clean (all changes staged)");
    } else {
        println!(
            "   Files staged for commit: {}",
            status_after_staging.entries.len()
        );
        for entry in &status_after_staging.entries {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }
    println!();

    // Create a commit
    println!("Creating commit...");
    let hash = repo.commit("Initial commit: Add project structure and basic files")?;

    println!("Commit created successfully!");
    println!("   Full hash: {}", hash);
    println!("   Short hash: {}", hash.short());
    println!();

    // Verify final status
    println!("Final repository status:");
    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("   Repository is clean - all changes committed!");
    } else {
        println!("   Repository still has uncommitted changes");
    }
    println!();

    // Clean up
    println!("Cleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Example completed successfully!");

    Ok(())
}

examples/branch_operations.rs (line 19)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

examples/config_operations.rs (line 91)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Configuration Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_config_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;

    // ==================== USER CONFIGURATION ====================

    println!("\n[CONFIG] Configuring git user settings...");

    // Set user configuration (convenience method)
    repo.config()
        .set_user("Alice Developer", "alice@example.com")?;
    println!("Set user configuration");

    // Verify user configuration
    let (name, email) = repo.config().get_user()?;
    println!("Current user: {} <{}>", name, email);

    // ==================== GENERAL CONFIGURATION ====================

    println!("\n[CONFIG] Setting repository configuration values...");

    // Set various git configuration values
    repo.config().set("core.autocrlf", "false")?;
    repo.config().set("core.ignorecase", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "simple")?;
    repo.config().set("branch.autosetupmerge", "always")?;

    println!("Set core configuration values");

    // Get and display configuration values
    println!("\n[CONFIG] Current repository configuration:");

    let configs = [
        "core.autocrlf",
        "core.ignorecase",
        "pull.rebase",
        "push.default",
        "branch.autosetupmerge",
    ];

    for config_key in &configs {
        match repo.config().get(config_key) {
            Ok(value) => println!("  {} = {}", config_key, value),
            Err(_) => println!("  {} = <not set>", config_key),
        }
    }

    // ==================== CONFIGURATION WITH COMMITS ====================

    println!("\n[COMMIT] Testing configuration with commit operations...");

    // Create a test file
    let test_file_path = repo_path.join("test.txt");
    fs::write(
        &test_file_path,
        "Hello from rustic-git configuration example!",
    )?;
    println!("Created test file: test.txt");

    // Stage the file
    repo.add(&["test.txt"])?;
    println!("Staged test.txt");

    // Create a commit (this will use our configured user)
    let commit_hash = repo.commit("Add test file with configuration example")?;
    println!("Created commit: {}", commit_hash.short());

    // ==================== CONFIGURATION MODIFICATION ====================

    println!("\n[UPDATE] Modifying configuration values...");

    // Change some configuration values
    repo.config().set("core.autocrlf", "true")?;
    repo.config()
        .set("user.email", "alice.developer@newcompany.com")?;

    println!("Updated configuration values");

    // Display updated values
    let autocrlf = repo.config().get("core.autocrlf")?;
    let (updated_name, updated_email) = repo.config().get_user()?;

    println!("Updated configuration:");
    println!("  core.autocrlf = {}", autocrlf);
    println!("  user: {} <{}>", updated_name, updated_email);

    // ==================== CONFIGURATION REMOVAL ====================

    println!("\n[REMOVE] Removing configuration values...");

    // Remove a configuration value
    repo.config().unset("branch.autosetupmerge")?;
    println!("Removed branch.autosetupmerge");

    // Try to get the removed value (should fail)
    match repo.config().get("branch.autosetupmerge") {
        Ok(value) => println!("Unexpected: branch.autosetupmerge = {}", value),
        Err(_) => println!("Confirmed: branch.autosetupmerge is not set"),
    }

    // ==================== ADVANCED CONFIGURATION ====================

    println!("\n[ADVANCED] Setting advanced configuration...");

    // Set some advanced git configuration
    repo.config().set("diff.tool", "vimdiff")?;
    repo.config().set("merge.tool", "vimdiff")?;
    repo.config().set("alias.st", "status")?;
    repo.config().set("alias.co", "checkout")?;
    repo.config().set("alias.br", "branch")?;
    repo.config().set("alias.ci", "commit")?;

    println!("Set advanced configuration (diff/merge tools and aliases)");

    // Display all custom configuration
    println!("\n[SUMMARY] Complete repository configuration summary:");

    let all_configs = [
        ("User", vec![("user.name", ""), ("user.email", "")]),
        ("Core", vec![("core.autocrlf", ""), ("core.ignorecase", "")]),
        ("Workflow", vec![("pull.rebase", ""), ("push.default", "")]),
        ("Tools", vec![("diff.tool", ""), ("merge.tool", "")]),
        (
            "Aliases",
            vec![
                ("alias.st", ""),
                ("alias.co", ""),
                ("alias.br", ""),
                ("alias.ci", ""),
            ],
        ),
    ];

    for (category, configs) in &all_configs {
        println!("\n  {}:", category);
        for (key, _) in configs {
            match repo.config().get(key) {
                Ok(value) => println!("    {} = {}", key, value),
                Err(_) => println!("    {} = <not set>", key),
            }
        }
    }

    // ==================== PRACTICAL EXAMPLE ====================

    println!("\n[TEAM] Practical example: Setting up repository for a team...");

    // Configure repository for team development
    repo.config().set("user.name", "Team Member")?;
    repo.config().set("user.email", "team@company.com")?;
    repo.config().set("core.autocrlf", "input")?;
    repo.config().set("core.safecrlf", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "current")?;
    repo.config().set("init.defaultBranch", "main")?;

    println!("Configured repository for team development");

    // Create another commit with the team configuration
    fs::write(
        repo_path.join("team.md"),
        "# Team Development\n\nThis repository is configured for team development.",
    )?;
    repo.add(&["team.md"])?;
    let team_commit = repo.commit("Add team development documentation")?;

    println!("Created team commit: {}", team_commit.short());

    // Final verification
    let (final_name, final_email) = repo.config().get_user()?;
    println!("\n[FINAL] Final repository configuration:");
    println!("  User: {} <{}>", final_name, final_email);
    println!("  Repository configured for team development workflow");

    // ==================== CLEANUP ====================

    println!("\n[CLEANUP] Cleaning up...");
    fs::remove_dir_all(&repo_path).expect("Failed to clean up example");
    println!("Example completed successfully!");

    Ok(())
}

Additional examples can be found in:

• examples/status_checking.rs
• examples/staging_operations.rs
• examples/diff_operations.rs
• examples/commit_workflows.rs
• examples/tag_operations.rs
• examples/remote_operations.rs
• examples/commit_history.rs
• examples/stash_operations.rs
• examples/file_lifecycle_operations.rs

pub fn commit_with_author(&self, message: &str, author: &str) -> Result<Hash>

Create a commit with the given message and author.

Arguments

• message - The commit message
• author - The author in format “Name email@example.com”

Returns

A Result containing the Hash of the new commit or a GitError.

Examples found in repository

examples/commit_workflows.rs (lines 151-154)

fn main() -> Result<()> {
    println!("Rustic Git - Commit Workflows Example\n");

    let repo_path = env::temp_dir().join("rustic_git_commit_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    // Initialize repository
    println!("Setting up repository for commit demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized\n");

    println!("=== Basic Commit Operations ===\n");

    // Create initial files
    println!("Creating initial project files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# Commit Demo Project\n\nThis project demonstrates commit workflows with rustic-git.\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello, Commit Demo!");
}
"#,
    )?;

    fs::write(
        repo_path.join("Cargo.toml"),
        r#"[package]
name = "commit-demo"
version = "0.1.0"
edition = "2021"
"#,
    )?;

    println!("Created README.md, src/main.rs, and Cargo.toml");

    // Stage and commit with basic commit()
    println!("\nStaging files for first commit...");
    repo.add_all()?;

    println!("Creating first commit with basic commit() method:");
    let first_hash = repo.commit("Initial commit: Add project structure")?;

    println!("First commit created!");
    display_hash_info(&first_hash, "First commit");
    println!();

    println!("=== Hash Type Demonstrations ===\n");

    println!("Hash type methods and usage:");

    // Demonstrate different ways to work with Hash
    let hash_as_string: String = first_hash.to_string();
    let hash_as_str: &str = first_hash.as_str();
    let short_hash: &str = first_hash.short();

    println!("   Hash conversions:");
    println!("      as_str(): '{}'", hash_as_str);
    println!("      short(): '{}'", short_hash);
    println!("      to_string(): '{}'", hash_as_string);
    println!("      Display: '{}'", first_hash);

    // Demonstrate Hash equality and cloning
    let cloned_hash = first_hash.clone();
    println!("\n   Hash operations:");
    println!("      Original == Clone: {}", first_hash == cloned_hash);
    println!(
        "      Hash length: {} characters",
        first_hash.as_str().len()
    );
    println!(
        "      Short hash length: {} characters",
        first_hash.short().len()
    );

    // Create Hash from different sources for demonstration
    let hash_from_string: Hash = "1234567890abcdef".to_string().into();
    let hash_from_str: Hash = "fedcba0987654321".into();

    println!("      Hash from String: {}", hash_from_string.short());
    println!("      Hash from &str: {}", hash_from_str.short());
    println!();

    println!("=== Commits with Custom Authors ===\n");

    // Create more files to commit with custom author
    println!("Adding features for custom author commit...");
    fs::create_dir_all(repo_path.join("tests"))?;

    fs::write(
        repo_path.join("src/lib.rs"),
        r#"//! Commit demo library

pub fn greet(name: &str) -> String {
    format!("Hello, {}! This is a commit demo.", name)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_greet() {
        assert_eq!(greet("Alice"), "Hello, Alice! This is a commit demo.");
    }
}
"#,
    )?;

    fs::write(
        repo_path.join("tests/integration_test.rs"),
        r#"use commit_demo::greet;

#[test]
fn test_integration() {
    let result = greet("Integration");
    assert!(result.contains("Integration"));
    assert!(result.contains("commit demo"));
}
"#,
    )?;

    println!("Created src/lib.rs and tests/integration_test.rs");

    // Stage and commit with custom author
    repo.add_all()?;
    println!("\nCreating commit with custom author:");
    let second_hash = repo.commit_with_author(
        "Add library code and tests\n\n- Implement greet function with proper documentation\n- Add unit tests and integration tests\n- Prepare for version 0.2.0 release",
        "Jane Developer <jane.dev@example.com>"
    )?;

    println!("Commit with custom author created!");
    display_hash_info(&second_hash, "Second commit (custom author)");
    println!();

    println!("=== Multiple Commit Workflow ===\n");

    // Demonstrate a series of commits
    let mut commit_hashes = vec![first_hash, second_hash];

    // Commit 3: Update version
    println!("Step 1: Update version information...");
    fs::write(
        repo_path.join("Cargo.toml"),
        r#"[package]
name = "commit-demo"
version = "0.2.0"
edition = "2021"
description = "A demo project for commit workflows"
"#,
    )?;

    repo.add(&["Cargo.toml"])?;
    let third_hash = repo.commit("Bump version to 0.2.0 and add description")?;
    commit_hashes.push(third_hash);

    // Commit 4: Add documentation
    println!("Step 2: Add documentation...");
    fs::write(
        repo_path.join("CHANGELOG.md"),
        r#"# Changelog

## [0.2.0] - 2024-01-01

### Added
- Library functionality with greet function
- Comprehensive test suite
- Project documentation

## [0.1.0] - 2024-01-01

### Added
- Initial project structure
- Basic Cargo configuration
"#,
    )?;

    repo.add(&["CHANGELOG.md"])?;
    let fourth_hash = repo.commit_with_author(
        "docs: Add CHANGELOG with version history",
        "Doc Writer <docs@example.com>",
    )?;
    commit_hashes.push(fourth_hash);

    // Commit 5: Final polish
    println!("Step 3: Final polish...");
    fs::write(
        repo_path.join("README.md"),
        r#"# Commit Demo Project

This project demonstrates commit workflows with rustic-git.

## Features

- Clean, type-safe Git operations
- Comprehensive commit history
- Multiple author support
- Hash management utilities

## Usage

```rust
use commit_demo::greet;

fn main() {
    println!("{}", greet("World"));
}
```

## Version

Current version: 0.2.0

See CHANGELOG.md for version history.
"#,
    )?;

    repo.add(&["README.md"])?;
    let fifth_hash = repo.commit("docs: Enhance README with usage examples and features")?;
    commit_hashes.push(fifth_hash);

    println!("\nComplete commit history created!");

    // Display all commits
    println!("\n=== Commit History Summary ===\n");

    for (i, hash) in commit_hashes.iter().enumerate() {
        println!("{}. Commit {}", i + 1, i + 1);
        display_hash_info(hash, &format!("Commit {}", i + 1));
        println!();
    }

    // Compare hashes
    println!("Hash comparisons:");
    println!(
        "   First commit == Last commit: {}",
        commit_hashes[0] == commit_hashes[4]
    );
    println!("   All hashes unique: {}", all_unique(&commit_hashes));

    // Show short hashes for all commits
    println!("\nAll commit short hashes:");
    for (i, hash) in commit_hashes.iter().enumerate() {
        println!("   {}: {}", i + 1, hash.short());
    }
    println!();

    println!("=== Error Handling for Commits ===\n");

    // Try to commit with nothing staged (should fail)
    println!("Testing commit with no staged changes:");
    match repo.commit("This should fail - no changes") {
        Ok(_hash) => println!("   Unexpectedly succeeded with empty commit"),
        Err(e) => {
            println!("   Expected error for empty commit: {:?}", e);
            println!("   This is normal behavior - Git requires changes to commit");
        }
    }

    // Try commit with custom author but no changes (should also fail)
    println!("\nTesting custom author commit with no changes:");
    match repo.commit_with_author("This should also fail", "Test Author <test@example.com>") {
        Ok(_hash) => println!("   Unexpectedly succeeded with empty custom author commit"),
        Err(e) => {
            println!(
                "   Expected error for empty commit with custom author: {:?}",
                e
            );
        }
    }

    // Test commit with empty message (Git might handle this differently)
    println!("\nTesting commit with empty message:");

    // Create a change to commit
    fs::write(repo_path.join("temp_for_empty_message.txt"), "temp content")?;
    repo.add(&["temp_for_empty_message.txt"])?;

    match repo.commit("") {
        Ok(hash) => {
            println!("   Commit with empty message succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commit messages");
        }
        Err(e) => {
            println!("   Empty commit message rejected: {:?}", e);
        }
    }

    println!();

    println!("=== Final Repository State ===\n");

    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("Repository is clean - all changes committed!");
    } else {
        println!(
            "Repository has {} uncommitted changes",
            final_status.entries.len()
        );
    }

    println!("\nWorkflow summary:");
    println!("   Total commits created: {}", commit_hashes.len());
    println!("   Hash examples demonstrated: [OK]");
    println!("   Custom author commits: [OK]");
    println!("   Error handling tested: [OK]");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Commit workflows example completed!");

    Ok(())
}

impl Repository

pub fn diff(&self) -> Result<DiffOutput>

Get diff between working directory and index (staged changes)

Shows changes that are not yet staged for commit.

Returns

A Result containing the DiffOutput or a GitError.

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let diff = repo.diff()?;
println!("Unstaged changes: {}", diff);

Examples found in repository

examples/diff_operations.rs (line 58)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

pub fn diff_staged(&self) -> Result<DiffOutput>

Get diff between index and HEAD (staged changes)

Shows changes that are staged for commit.

Returns

A Result containing the DiffOutput or a GitError.

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let diff = repo.diff_staged()?;
println!("Staged changes: {}", diff);

Examples found in repository

examples/diff_operations.rs (line 84)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

pub fn diff_head(&self) -> Result<DiffOutput>

Get diff between working directory and HEAD

Shows all changes (both staged and unstaged) compared to the last commit.

Returns

A Result containing the DiffOutput or a GitError.

Examples found in repository

examples/diff_operations.rs (line 188)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

pub fn diff_commits(&self, from: &Hash, to: &Hash) -> Result<DiffOutput>

Get diff between two commits

Arguments

• from - The starting commit hash
• to - The ending commit hash

Returns

A Result containing the DiffOutput or a GitError.

Example

use rustic_git::{Repository, Hash};

let repo = Repository::open(".")?;
let from = Hash::from("abc123");
let to = Hash::from("def456");
let diff = repo.diff_commits(&from, &to)?;
println!("Changes between commits: {}", diff);

Examples found in repository

examples/diff_operations.rs (line 125)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

pub fn diff_with_options(&self, options: &DiffOptions) -> Result<DiffOutput>

Get diff with custom options

Arguments

• options - The diff options to use

Returns

A Result containing the DiffOutput or a GitError.

Example

use rustic_git::{Repository, DiffOptions};

let repo = Repository::open(".")?;
let options = DiffOptions::new()
    .ignore_whitespace()
    .context_lines(5);
let diff = repo.diff_with_options(&options)?;
println!("Diff with options: {}", diff);

Examples found in repository

examples/diff_operations.rs (line 101)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

impl Repository

pub fn checkout_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Restore file from HEAD, discarding local changes

This is equivalent to git checkout HEAD -- <file> and will restore the file to its state in the last commit, discarding any local changes.

Arguments

• path - Path to the file to restore

Example

use rustic_git::Repository;

// Restore a modified file to its last committed state
repo.checkout_file("modified_file.txt")?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 99)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn restore<P: AsRef<Path>>( &self, paths: &[P], options: RestoreOptions, ) -> Result<()>

Restore files with advanced options

This provides access to git’s restore command with full control over source, staging area, and working tree restoration.

Arguments

• paths - Paths to restore
• options - Restore options

Example

use rustic_git::{Repository, RestoreOptions};

// Restore from a specific commit
let options = RestoreOptions::new()
    .with_source("HEAD~1")
    .with_worktree();
repo.restore(&["file.txt"], options)?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 130)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn reset_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Unstage a specific file, removing it from the staging area

This is equivalent to git reset HEAD -- <file> and removes the file from the staging area while keeping changes in the working directory.

Arguments

• path - Path to the file to unstage

Example

use rustic_git::Repository;

// Unstage a previously staged file
repo.reset_file("staged_file.txt")?;

Examples found in repository

examples/reset_operations.rs (line 137)

fn demonstrate_file_resets(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating File-Specific Resets ---\n");

    // Create some files and stage them
    println!("1. Creating and staging multiple files...");

    let file_a = temp_dir.join("fileA.txt");
    let file_b = temp_dir.join("fileB.txt");

    fs::write(&file_a, "Content A")?;
    fs::write(&file_b, "Content B")?;

    repo.add(&["fileA.txt", "fileB.txt"])?;
    println!("   Staged fileA.txt and fileB.txt");

    show_repo_state(repo)?;

    // Reset a single file (using existing reset_file from files.rs)
    println!("\n2. Resetting single file (fileA.txt)...");
    repo.reset_file("fileA.txt")?;

    println!("   After resetting fileA.txt:");
    show_repo_state(repo)?;
    println!("   Note: fileA.txt is unstaged, fileB.txt remains staged");

    // Demonstrate HEAD reset (unstage all changes)
    println!("\n3. Performing mixed reset to HEAD (unstage all)...");
    repo.reset_mixed("HEAD")?;

    println!("   After reset HEAD:");
    show_repo_state(repo)?;
    println!("   Note: All staged changes are now unstaged");

    Ok(())
}

examples/file_lifecycle_operations.rs (line 159)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn rm<P: AsRef<Path>>(&self, paths: &[P]) -> Result<()>

Remove files from the repository

This removes files from both the working directory and the repository, equivalent to git rm <files>.

Arguments

• paths - Paths to remove

Example

use rustic_git::Repository;

// Remove files from repository
repo.rm(&["unwanted_file.txt", "old_dir/"])?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 199)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn rm_with_options<P: AsRef<Path>>( &self, paths: &[P], options: RemoveOptions, ) -> Result<()>

Remove files with advanced options

This provides full control over file removal with options for force, recursive, cached-only removal, etc.

Arguments

• paths - Paths to remove
• options - Remove options

Example

use rustic_git::{Repository, RemoveOptions};

// Remove from index only, keep files in working tree
let options = RemoveOptions::new().with_cached();
repo.rm_with_options(&["keep_local.txt"], options)?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 206)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn mv<P: AsRef<Path>, Q: AsRef<Path>>( &self, source: P, destination: Q, ) -> Result<()>

Move or rename a file or directory

This is equivalent to git mv <source> <destination> and will move the file both in the working directory and in the repository.

Arguments

• source - Source path
• destination - Destination path

Example

use rustic_git::Repository;

// Rename a file
repo.mv("old_name.txt", "new_name.txt")?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 242)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn mv_with_options<P: AsRef<Path>, Q: AsRef<Path>>( &self, source: P, destination: Q, options: MoveOptions, ) -> Result<()>

Move files with advanced options

This provides full control over file moving with options for force, verbose output, and dry run mode.

Arguments

• source - Source path
• destination - Destination path
• options - Move options

Example

use rustic_git::{Repository, MoveOptions};

// Force move even if destination exists
let options = MoveOptions::new().with_force();
repo.mv_with_options("source.txt", "existing.txt", options)?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 265)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn ignore_add(&self, patterns: &[&str]) -> Result<()>

Add patterns to .gitignore file

This adds the specified patterns to the repository’s .gitignore file, creating the file if it doesn’t exist.

Arguments

• patterns - Patterns to add to .gitignore

Example

use rustic_git::Repository;

// Add patterns to .gitignore
repo.ignore_add(&["*.tmp", "build/", "node_modules/"])?;

Examples found in repository

examples/file_lifecycle_operations.rs (lines 282-289)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn ignore_check<P: AsRef<Path>>(&self, path: P) -> Result<bool>

Check if a file is ignored by .gitignore patterns

This uses git check-ignore to determine if a file would be ignored by the current .gitignore patterns.

Arguments

• path - Path to check

Returns

• Ok(true) if the file is ignored
• Ok(false) if the file is not ignored
• Err(GitError) if the command fails

Example

use rustic_git::Repository;

// Check if a file is ignored
let is_ignored = repo.ignore_check("temp_file.tmp")?;

Examples found in repository

examples/file_lifecycle_operations.rs (line 316)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

pub fn ignore_list(&self) -> Result<Vec<String>>

List current ignore patterns from .gitignore

This reads the .gitignore file and returns all non-empty, non-comment lines.

Returns

• Vector of ignore patterns

Example

use rustic_git::Repository;

// List all ignore patterns
let patterns = repo.ignore_list()?;
for pattern in patterns {
    println!("Ignoring: {}", pattern);
}

Examples found in repository

examples/file_lifecycle_operations.rs (line 277)

fn main() -> Result<()> {
    println!("Rustic Git - File Lifecycle Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_files_example");
    let repo_path = base_path.join("main_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for file lifecycle demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Set up git configuration for commits
    repo.config().set_user("Demo User", "demo@example.com")?;

    // Create initial project structure
    fs::create_dir_all(repo_path.join("src"))?;
    fs::create_dir_all(repo_path.join("docs"))?;
    fs::create_dir_all(repo_path.join("tests"))?;

    let files = [
        (
            "README.md",
            "# File Lifecycle Demo\n\nDemonstrating rustic-git file management capabilities.",
        ),
        (
            "src/main.rs",
            "fn main() {\n    println!(\"Hello, world!\");\n}",
        ),
        (
            "src/lib.rs",
            "//! Library module\n\npub fn greet() {\n    println!(\"Hello from lib!\");\n}",
        ),
        ("docs/guide.md", "# User Guide\n\nThis is the user guide."),
        (
            "tests/integration.rs",
            "#[test]\nfn test_basic() {\n    assert_eq!(2 + 2, 4);\n}",
        ),
    ];

    for (path, content) in &files {
        fs::write(repo_path.join(path), content)?;
    }

    repo.add(&files.iter().map(|(path, _)| *path).collect::<Vec<_>>())?;
    let initial_commit = repo.commit("Initial project setup")?;
    println!("Created initial commit: {}\n", initial_commit.short());

    println!("=== File Restoration Operations ===\n");

    // Modify some files
    println!("Modifying files to demonstrate restoration...");
    fs::write(
        repo_path.join("README.md"),
        "# Modified README\n\nThis content has been changed.",
    )?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Modified main!\");\n    println!(\"Added new line!\");\n}",
    )?;

    println!("   Modified README.md and src/main.rs");

    // Show current status
    let status = repo.status()?;
    println!(
        "   Files with modifications: {}",
        status.unstaged_files().count()
    );
    for entry in status.unstaged_files() {
        println!("     - {}", entry.path.display());
    }
    println!();

    // Restore single file with checkout_file
    println!("Restoring README.md using checkout_file():");
    repo.checkout_file("README.md")?;
    let restored_content = fs::read_to_string(repo_path.join("README.md"))?;
    println!("   ✓ README.md restored to original state");
    println!(
        "   Content preview: {:?}",
        restored_content.lines().next().unwrap_or("")
    );
    println!();

    // Demonstrate advanced restore with options
    println!("Creating second commit for restore demonstration...");
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! Advanced module\n\npub fn advanced_function() {\n    println!(\"Advanced functionality\");\n}",
    )?;
    repo.add(&["src/advanced.rs"])?;
    let second_commit = repo.commit("Add advanced module")?;
    println!("   Second commit: {}", second_commit.short());

    // Modify the advanced file
    fs::write(
        repo_path.join("src/advanced.rs"),
        "//! HEAVILY MODIFIED\n\npub fn broken_function() {\n    panic!(\"This is broken!\");\n}",
    )?;
    println!("   Modified src/advanced.rs");

    // Restore from specific commit using restore with options
    println!("Restoring src/advanced.rs from specific commit using restore():");
    let restore_options = RestoreOptions::new()
        .with_source(format!("{}", second_commit))
        .with_worktree();
    repo.restore(&["src/advanced.rs"], restore_options)?;

    let restored_advanced = fs::read_to_string(repo_path.join("src/advanced.rs"))?;
    println!("   ✓ File restored from commit {}", second_commit.short());
    println!(
        "   Content preview: {:?}",
        restored_advanced.lines().next().unwrap_or("")
    );
    println!();

    println!("=== Staging Area Operations ===\n");

    // Modify and stage files
    println!("Demonstrating staging area manipulation...");
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! STAGED CHANGES\n\npub fn new_function() {\n    println!(\"This will be staged\");\n}",
    )?;
    repo.add(&["src/lib.rs"])?;
    println!("   Modified and staged src/lib.rs");

    let status = repo.status()?;
    println!("   Staged files: {}", status.staged_files().count());
    for entry in status.staged_files() {
        println!("     - {}", entry.path.display());
    }

    // Unstage the file
    println!("Unstaging src/lib.rs using reset_file():");
    repo.reset_file("src/lib.rs")?;

    let status_after_reset = repo.status()?;
    println!("   ✓ File unstaged (now in modified files)");
    println!(
        "   Staged files: {}",
        status_after_reset.staged_files().count()
    );
    println!(
        "   Modified files: {}",
        status_after_reset.unstaged_files().count()
    );
    println!();

    println!("=== File Removal Operations ===\n");

    // Create files for removal demonstration
    println!("Creating files for removal demonstration...");
    fs::write(repo_path.join("temp_file.txt"), "This is a temporary file")?;
    fs::write(
        repo_path.join("docs/old_doc.md"),
        "# Old Documentation\n\nThis document is outdated.",
    )?;
    fs::create_dir_all(repo_path.join("old_directory"))?;
    fs::write(
        repo_path.join("old_directory/nested_file.txt"),
        "Nested content",
    )?;

    // Add and commit these files
    repo.add(&[
        "temp_file.txt",
        "docs/old_doc.md",
        "old_directory/nested_file.txt",
    ])?;
    repo.commit("Add files for removal demo")?;
    println!("   Created and committed files for removal");

    // Basic file removal
    println!("Removing temp_file.txt using rm():");
    repo.rm(&["temp_file.txt"])?;
    println!("   ✓ temp_file.txt removed from repository and working tree");
    assert!(!repo_path.join("temp_file.txt").exists());

    // Remove from index only (keep in working tree)
    println!("Removing docs/old_doc.md from index only using rm_with_options():");
    let cached_remove_options = RemoveOptions::new().with_cached();
    repo.rm_with_options(&["docs/old_doc.md"], cached_remove_options)?;

    println!("   ✓ File removed from index but kept in working tree");
    assert!(repo_path.join("docs/old_doc.md").exists());
    let content = fs::read_to_string(repo_path.join("docs/old_doc.md"))?;
    println!(
        "   Working tree content still available: {:?}",
        content.lines().next().unwrap_or("")
    );

    // Recursive removal
    println!("Removing old_directory/ recursively:");
    let recursive_options = RemoveOptions::new().with_recursive();
    repo.rm_with_options(&["old_directory/"], recursive_options)?;
    println!("   ✓ Directory and contents removed recursively");
    assert!(!repo_path.join("old_directory").exists());
    println!();

    println!("=== File Move/Rename Operations ===\n");

    // Create files for move demonstration
    println!("Creating files for move/rename demonstration...");
    fs::write(repo_path.join("old_name.txt"), "This file will be renamed")?;
    fs::create_dir_all(repo_path.join("source_dir"))?;
    fs::write(
        repo_path.join("source_dir/movable.txt"),
        "This file will be moved",
    )?;
    fs::create_dir_all(repo_path.join("target_dir"))?;

    repo.add(&["old_name.txt", "source_dir/movable.txt"])?;
    repo.commit("Add files for move demo")?;
    println!("   Created files for move demonstration");

    // Simple rename
    println!("Renaming old_name.txt to new_name.txt using mv():");
    repo.mv("old_name.txt", "new_name.txt")?;

    assert!(!repo_path.join("old_name.txt").exists());
    assert!(repo_path.join("new_name.txt").exists());
    let content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("   ✓ File renamed successfully");
    println!("   Content preserved: {:?}", content.trim());

    // Move file to different directory
    println!("Moving source_dir/movable.txt to target_dir/ using mv():");
    repo.mv("source_dir/movable.txt", "target_dir/movable.txt")?;

    assert!(!repo_path.join("source_dir/movable.txt").exists());
    assert!(repo_path.join("target_dir/movable.txt").exists());
    println!("   ✓ File moved to different directory");

    // Demonstrate move with options (dry run)
    fs::write(repo_path.join("test_move.txt"), "Test content for dry run")?;
    repo.add(&["test_move.txt"])?;
    repo.commit("Add test file for dry run demo")?;

    println!("Demonstrating dry run move (won't actually move):");
    let dry_run_options = MoveOptions::new().with_dry_run().with_verbose();
    repo.mv_with_options("test_move.txt", "would_be_moved.txt", dry_run_options)?;

    // File should still exist at original location
    assert!(repo_path.join("test_move.txt").exists());
    assert!(!repo_path.join("would_be_moved.txt").exists());
    println!("   ✓ Dry run completed - no actual move performed");
    println!();

    println!("=== .gitignore Management ===\n");

    // Initially no ignore patterns
    println!("Checking initial .gitignore state:");
    let initial_patterns = repo.ignore_list()?;
    println!("   Initial ignore patterns: {}", initial_patterns.len());

    // Add ignore patterns
    println!("Adding ignore patterns...");
    repo.ignore_add(&[
        "*.tmp",
        "*.log",
        "build/",
        "node_modules/",
        ".DS_Store",
        "*.secret",
    ])?;
    println!("   Added 6 ignore patterns to .gitignore");

    // List current patterns
    let patterns = repo.ignore_list()?;
    println!("   Current ignore patterns: {}", patterns.len());
    for (i, pattern) in patterns.iter().enumerate() {
        println!("     {}. {}", i + 1, pattern);
    }

    // Create test files to check ignore status
    println!("\nCreating test files to check ignore status...");
    let test_files = [
        ("regular_file.txt", false),
        ("temp_file.tmp", true),
        ("debug.log", true),
        ("important.secret", true),
        ("normal.md", false),
    ];

    for (filename, _) in &test_files {
        fs::write(repo_path.join(filename), "test content")?;
    }

    // Check ignore status for each file
    println!("Checking ignore status for test files:");
    for (filename, expected_ignored) in &test_files {
        let is_ignored = repo.ignore_check(filename)?;
        let status_symbol = if is_ignored { "🚫" } else { "✅" };
        println!(
            "   {} {} - {}",
            status_symbol,
            filename,
            if is_ignored { "IGNORED" } else { "TRACKED" }
        );

        // Verify expectation
        assert_eq!(
            is_ignored, *expected_ignored,
            "Ignore status mismatch for {}",
            filename
        );
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to checkout non-existent file
    println!("   Attempting to checkout non-existent file:");
    match repo.checkout_file("nonexistent.txt") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to reset non-existent file
    println!("   Attempting to reset non-staged file:");
    match repo.reset_file("new_name.txt") {
        Ok(_) => println!("     ✓ Reset succeeded (file not staged, no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to remove non-existent file
    println!("   Attempting to remove non-existent file:");
    match repo.rm(&["definitely_not_here.txt"]) {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove with ignore-unmatch option
    println!("   Attempting to remove with ignore-unmatch option:");
    let ignore_unmatch_options = RemoveOptions::new().with_ignore_unmatch();
    match repo.rm_with_options(&["also_not_here.txt"], ignore_unmatch_options) {
        Ok(_) => println!("     ✓ Succeeded with ignore-unmatch (no error)"),
        Err(e) => println!("     Error: {}", e),
    }

    // Try to move to existing file without force
    fs::write(repo_path.join("existing_target.txt"), "existing content")?;
    repo.add(&["existing_target.txt"])?;
    repo.commit("Add existing target")?;

    println!("   Attempting to move to existing file without force:");
    match repo.mv("test_move.txt", "existing_target.txt") {
        Ok(_) => println!("     Unexpected success (git may have overwritten)"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }
    println!();

    println!("=== Advanced Restore Operations ===\n");

    // Demonstrate restore with staged and worktree options
    println!("Demonstrating advanced restore with staging area...");

    // Modify file and stage it
    fs::write(repo_path.join("new_name.txt"), "staged changes")?;
    repo.add(&["new_name.txt"])?;

    // Modify it again in working tree
    fs::write(repo_path.join("new_name.txt"), "working tree changes")?;

    println!("   File has both staged and working tree changes");

    // Restore only staged area
    println!("   Restoring staged changes only:");
    let staged_restore = RestoreOptions::new().with_staged();
    repo.restore(&["new_name.txt"], staged_restore)?;

    let content_after_staged_restore = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Staged changes restored, working tree preserved");
    println!(
        "     Working tree content: {:?}",
        content_after_staged_restore.trim()
    );

    // Restore working tree
    println!("   Restoring working tree:");
    let worktree_restore = RestoreOptions::new().with_worktree();
    repo.restore(&["new_name.txt"], worktree_restore)?;

    let final_content = fs::read_to_string(repo_path.join("new_name.txt"))?;
    println!("     ✓ Working tree restored to committed state");
    println!("     Final content: {:?}", final_content.trim());
    println!();

    println!("=== Repository State Summary ===\n");

    let final_status = repo.status()?;
    println!("Final repository state:");
    println!("   Clean repository: {}", final_status.is_clean());
    println!("   Staged files: {}", final_status.staged_files().count());
    println!(
        "   Modified files: {}",
        final_status.unstaged_files().count()
    );
    println!(
        "   Untracked files: {}",
        final_status.untracked_entries().count()
    );

    if !final_status.is_clean() {
        println!("\n   Remaining changes:");
        for entry in final_status.staged_files() {
            println!("     Staged: {}", entry.path.display());
        }
        for entry in final_status.unstaged_files() {
            println!("     Modified: {}", entry.path.display());
        }
        for entry in final_status.untracked_entries() {
            println!("     Untracked: {}", entry.path.display());
        }
    }

    // Show .gitignore content
    let final_patterns = repo.ignore_list()?;
    println!("\n   .gitignore patterns: {}", final_patterns.len());
    for pattern in final_patterns {
        println!("     - {}", pattern);
    }

    println!("\n=== Summary ===\n");

    println!("File lifecycle operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    println!("\nOperations demonstrated:");
    println!("  ✓ File restoration from HEAD (checkout_file)");
    println!("  ✓ Advanced file restoration with options (restore)");
    println!("  ✓ Unstaging files (reset_file)");
    println!("  ✓ File removal with various options (rm, rm_with_options)");
    println!("  ✓ File moving and renaming (mv, mv_with_options)");
    println!("  ✓ .gitignore pattern management (ignore_add, ignore_list, ignore_check)");
    println!("  ✓ Staged vs working tree restoration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Dry run and verbose options");
    println!("  ✓ Recursive and cached removal options");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("File lifecycle operations example completed!");

    Ok(())
}

impl Repository

pub fn log(&self) -> Result<CommitLog>

Get commit history with default options

Examples found in repository

examples/commit_history.rs (line 82)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn recent_commits(&self, count: usize) -> Result<CommitLog>

Get recent N commits

Examples found in repository

examples/merge_operations.rs (line 145)

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/commit_history.rs (line 92)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn log_with_options(&self, options: &LogOptions) -> Result<CommitLog>

Get commit history with custom options

Examples found in repository

examples/commit_history.rs (line 121)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn log_range(&self, from: &Hash, to: &Hash) -> Result<CommitLog>

Get commits in a range between two commits

Examples found in repository

examples/commit_history.rs (line 206)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn log_for_paths(&self, paths: &[impl AsRef<Path>]) -> Result<CommitLog>

Get commits that affected specific paths

Examples found in repository

examples/commit_history.rs (line 129)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

pub fn show_commit(&self, hash: &Hash) -> Result<CommitDetails>

Get detailed information about a specific commit

Examples found in repository

examples/commit_history.rs (line 138)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_commit_history_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create several commits to build history
    println!("\n=== Building Commit History ===");

    // First commit
    fs::write(
        test_path.join("README.md"),
        "# Commit History Demo\n\nA demonstration of rustic-git log functionality.",
    )
    .unwrap();
    repo.add(&["README.md"])?;
    let commit1 = repo.commit("Initial commit - add README")?;
    println!("Created commit 1: {} - Initial commit", commit1.short());

    // Second commit
    fs::create_dir_all(test_path.join("src")).unwrap();
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, world!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit2 = repo.commit("Add main.rs with Hello World")?;
    println!("Created commit 2: {} - Add main.rs", commit2.short());

    // Third commit
    fs::write(
        test_path.join("src/lib.rs"),
        "pub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}",
    )
    .unwrap();
    repo.add(&["src/lib.rs"])?;
    let commit3 = repo.commit("Add library module with greet function")?;
    println!("Created commit 3: {} - Add lib.rs", commit3.short());

    // Fourth commit
    fs::write(
        test_path.join("Cargo.toml"),
        "[package]\nname = \"demo\"\nversion = \"0.1.0\"\nedition = \"2021\"",
    )
    .unwrap();
    repo.add(&["Cargo.toml"])?;
    let commit4 = repo.commit("Add Cargo.toml configuration")?;
    println!("Created commit 4: {} - Add Cargo.toml", commit4.short());

    // Fifth commit - bug fix
    fs::write(
        test_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, rustic-git!\");\n}",
    )
    .unwrap();
    repo.add(&["src/main.rs"])?;
    let commit5 = repo.commit("Fix greeting message in main")?;
    println!("Created commit 5: {} - Fix greeting", commit5.short());

    // Sixth commit - documentation
    fs::write(test_path.join("README.md"), "# Commit History Demo\n\nA demonstration of rustic-git log functionality.\n\n## Features\n\n- Greeting functionality\n- Command line interface\n").unwrap();
    repo.add(&["README.md"])?;
    let commit6 = repo.commit("Update README with features section")?;
    println!("Created commit 6: {} - Update README", commit6.short());

    println!("Built commit history with 6 commits");

    // Basic log operations
    println!("\n=== Basic Log Operations ===");

    let all_commits = repo.log()?;
    println!("Total commits in repository: {}", all_commits.len());

    println!("\nAll commits (most recent first):");
    for (i, commit) in all_commits.iter().enumerate() {
        println!("  {}. {}", i + 1, commit);
    }

    // Recent commits
    println!("\n=== Recent Commits ===");
    let recent = repo.recent_commits(3)?;
    println!("Last 3 commits:");
    for commit in recent.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
        if let Some(body) = &commit.message.body {
            println!("    Body: {}", body);
        }
    }

    // Advanced filtering with LogOptions
    println!("\n=== Advanced Filtering ===");

    // Filter by message content
    let fix_commits = all_commits.with_message_containing("fix");
    println!("Commits with 'fix' in message:");
    for commit in fix_commits {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Filter by date (recent commits)
    let now = Utc::now();
    let recent_commits = all_commits.since(now - Duration::minutes(5));
    println!("\nCommits from last 5 minutes: {}", recent_commits.count());

    // Using LogOptions for advanced queries
    println!("\n=== LogOptions Advanced Queries ===");

    // Get commits with grep
    let opts = LogOptions::new().max_count(10).grep("README".to_string());
    let readme_commits = repo.log_with_options(&opts)?;
    println!("Commits mentioning 'README': {}", readme_commits.len());
    for commit in readme_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Get commits affecting specific paths
    println!("\n=== Path-Specific History ===");
    let src_commits = repo.log_for_paths(&["src/"])?;
    println!("Commits affecting src/ directory: {}", src_commits.len());
    for commit in src_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Show detailed commit information
    println!("\n=== Detailed Commit Information ===");

    let commit_details = repo.show_commit(&commit3)?;
    println!("Detailed info for commit {}:", commit3.short());
    println!("  Author: {}", commit_details.commit.author);
    println!("  Committer: {}", commit_details.commit.committer);
    println!(
        "  Timestamp: {}",
        commit_details
            .commit
            .timestamp
            .format("%Y-%m-%d %H:%M:%S UTC")
    );
    println!("  Message: {}", commit_details.commit.message.subject);
    println!("  Parents: {}", commit_details.commit.parents.len());
    for parent in commit_details.commit.parents.iter() {
        println!("    - {}", parent.short());
    }
    println!("  Files changed: {}", commit_details.files_changed.len());
    for file in &commit_details.files_changed {
        println!("    - {}", file.display());
    }
    println!(
        "  Changes: +{} -{}",
        commit_details.insertions, commit_details.deletions
    );

    // Commit analysis
    println!("\n=== Commit Analysis ===");

    let merge_commits: Vec<_> = all_commits.merges_only().collect();
    let regular_commits: Vec<_> = all_commits.no_merges().collect();

    println!("Repository statistics:");
    println!("  Total commits: {}", all_commits.len());
    println!("  Merge commits: {}", merge_commits.len());
    println!("  Regular commits: {}", regular_commits.len());

    if let Some(first_commit) = all_commits.first() {
        println!(
            "  Most recent: {} ({})",
            first_commit.hash.short(),
            first_commit.message.subject
        );
    }

    if let Some(last_commit) = all_commits.last() {
        println!(
            "  Oldest: {} ({})",
            last_commit.hash.short(),
            last_commit.message.subject
        );
    }

    // Search operations
    println!("\n=== Search Operations ===");

    // Find by hash
    if let Some(found) = all_commits.find_by_hash(&commit2) {
        println!("Found commit by full hash: {}", found.message.subject);
    }

    // Find by short hash
    if let Some(found) = all_commits.find_by_short_hash(commit4.short()) {
        println!("Found commit by short hash: {}", found.message.subject);
    }

    // Commit range operations
    println!("\n=== Commit Range Operations ===");

    let range_commits = repo.log_range(&commit2, &commit5)?;
    println!(
        "Commits in range {}..{}: {}",
        commit2.short(),
        commit5.short(),
        range_commits.len()
    );
    for commit in range_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Advanced LogOptions demonstration
    println!("\n=== Advanced LogOptions Usage ===");

    let advanced_opts = LogOptions::new()
        .max_count(5)
        .no_merges(true)
        .paths(vec!["src/main.rs".into()]);

    let filtered_commits = repo.log_with_options(&advanced_opts)?;
    println!(
        "Non-merge commits affecting src/main.rs (max 5): {}",
        filtered_commits.len()
    );
    for commit in filtered_commits.iter() {
        println!("  {} - {}", commit.hash.short(), commit.message.subject);
    }

    // Commit message analysis
    println!("\n=== Commit Message Analysis ===");

    let total_commits = all_commits.len();
    let commits_with_body: Vec<_> = all_commits
        .iter()
        .filter(|c| c.message.body.is_some())
        .collect();

    println!("Message statistics:");
    println!("  Total commits: {}", total_commits);
    println!("  Commits with body text: {}", commits_with_body.len());
    println!(
        "  Commits with subject only: {}",
        total_commits - commits_with_body.len()
    );

    // Display commit types by analyzing subjects
    let fix_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("fix"))
        .count();
    let add_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("add"))
        .count();
    let update_count = all_commits
        .iter()
        .filter(|c| c.message.subject.to_lowercase().contains("update"))
        .count();

    println!("  Commit types:");
    println!("    - Fix commits: {}", fix_count);
    println!("    - Add commits: {}", add_count);
    println!("    - Update commits: {}", update_count);
    println!(
        "    - Other commits: {}",
        total_commits - fix_count - add_count - update_count
    );

    // Timeline view
    println!("\n=== Timeline View ===");

    println!("Commit timeline (oldest to newest):");
    let commits: Vec<_> = all_commits.iter().collect();
    for commit in commits.iter().rev() {
        let commit_type = if commit.is_merge() { "MERGE" } else { "COMMIT" };
        println!(
            "  {} {} {} - {}",
            commit.timestamp.format("%H:%M:%S"),
            commit_type,
            commit.hash.short(),
            commit.message.subject
        );
    }

    // Summary
    println!("\n=== Summary ===");

    println!("Commit history demonstration completed!");
    println!("  Repository: {}", test_path.display());
    println!("  Total commits analyzed: {}", all_commits.len());
    println!("  Hash examples:");
    for commit in all_commits.iter().take(3) {
        println!("    - Full: {}", commit.hash.as_str());
        println!("      Short: {}", commit.hash.short());
    }

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

impl Repository

pub fn merge(&self, branch: &str) -> Result<MergeStatus>

Merge the specified branch into the current branch.

Performs a merge using default options (allow fast-forward, no custom message).

Arguments

• branch - The name of the branch to merge into the current branch

Returns

A Result containing the MergeStatus which indicates the outcome of the merge.

Examples

use rustic_git::{Repository, MergeStatus};

let repo = Repository::open(".")?;
match repo.merge("feature-branch")? {
    MergeStatus::Success(hash) => println!("Merge commit: {}", hash),
    MergeStatus::FastForward(hash) => println!("Fast-forwarded to: {}", hash),
    MergeStatus::UpToDate => println!("Already up to date"),
    MergeStatus::Conflicts(files) => println!("Conflicts in: {:?}", files),
}

Examples found in repository

examples/merge_operations.rs (line 75)

fn demonstrate_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Fast-Forward Merge ---\n");

    // Create initial commit
    println!("1. Creating initial commit on master...");
    let file1_path = temp_dir.join("README.md");
    fs::write(&file1_path, "# Project\n\nInitial content")?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit")?;
    println!("   Created commit: {}", initial_commit);

    // Create feature branch and add commits
    println!("\n2. Creating feature branch and adding commits...");
    repo.checkout_new("feature/fast-forward", None)?;

    let file2_path = temp_dir.join("feature.txt");
    fs::write(&file2_path, "New feature implementation")?;
    repo.add(&["feature.txt"])?;
    let feature_commit = repo.commit("Add new feature")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;
    println!("   Switched to master");

    // Perform fast-forward merge
    println!("\n4. Performing fast-forward merge...");
    let merge_status = repo.merge("feature/fast-forward")?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed!");
            println!("   New HEAD: {}", hash);
            println!("   Both files are now present on master");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    println!("   Files in repository:");
    for file in ["README.md", "feature.txt"] {
        if temp_dir.join(file).exists() {
            println!("     ✓ {}", file);
        }
    }

    Ok(())
}

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

pub fn merge_with_options( &self, branch: &str, options: MergeOptions, ) -> Result<MergeStatus>

Merge the specified branch with custom options.

Provides full control over merge behavior including fast-forward mode, merge strategy, and commit message.

Arguments

• branch - The name of the branch to merge into the current branch
• options - Merge options controlling the merge behavior

Returns

A Result containing the MergeStatus which indicates the outcome of the merge.

Examples

use rustic_git::{Repository, MergeOptions, FastForwardMode};

let repo = Repository::open(".")?;
let options = MergeOptions::new()
    .with_fast_forward(FastForwardMode::Never)
    .with_message("Merge feature into main".to_string());

let status = repo.merge_with_options("feature-branch", options)?;

Examples found in repository

examples/merge_operations.rs (line 132)

fn demonstrate_no_fast_forward_merge(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating No-Fast-Forward Merge ---\n");

    // Add a commit to master to prevent fast-forward
    println!("1. Adding commit to master...");
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nInitial content\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_commit = repo.commit("Update documentation")?;
    println!("   Master commit: {}", master_commit);

    // Create another feature branch
    println!("\n2. Creating another feature branch...");
    repo.checkout_new("feature/no-ff", None)?;

    let config_path = temp_dir.join("config.yaml");
    fs::write(&config_path, "app:\n  name: example\n  version: 1.0")?;
    repo.add(&["config.yaml"])?;
    let config_commit = repo.commit("Add configuration file")?;
    println!("   Config commit: {}", config_commit);

    // Switch back to master
    println!("\n3. Switching back to master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Perform no-fast-forward merge
    println!("\n4. Performing no-fast-forward merge...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Never)
        .with_message("Merge feature/no-ff into master".to_string());

    let merge_status = repo.merge_with_options("feature/no-ff", options)?;

    match merge_status {
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created!");
            println!("   Merge commit: {}", hash);
            println!("   Created explicit merge commit preserving branch history");
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    // Show the commit history
    println!("\n5. Recent commit history:");
    let commits = repo.recent_commits(3)?;
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "   {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

pub fn merge_in_progress(&self) -> Result<bool>

Check if a merge is currently in progress.

Returns true if there is an ongoing merge that needs to be completed or aborted.

Returns

A Result containing a boolean indicating whether a merge is in progress.

Examples found in repository

examples/merge_operations.rs (line 202)

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

pub fn abort_merge(&self) -> Result<()>

Abort an in-progress merge.

Cancels the current merge operation and restores the repository to the state before the merge was started. This is useful when merge conflicts occur and you want to cancel the merge instead of resolving conflicts.

Returns

A Result indicating success or failure of the abort operation.

Examples

use rustic_git::Repository;

let repo = Repository::open(".")?;
if repo.merge_in_progress()? {
    repo.abort_merge()?;
    println!("Merge aborted");
}

Examples found in repository

examples/merge_operations.rs (line 222)

fn demonstrate_merge_conflicts(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Conflicts ---\n");

    // Create conflicting branch
    println!("1. Creating branch with conflicting changes...");
    repo.checkout_new("feature/conflict", None)?;

    // Modify the same file differently
    let readme_path = temp_dir.join("README.md");
    fs::write(
        &readme_path,
        "# Project\n\nFeature branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let feature_commit = repo.commit("Update README from feature branch")?;
    println!("   Feature commit: {}", feature_commit);

    // Switch back to master and make conflicting change
    println!("\n2. Making conflicting change on master...");
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    fs::write(
        &readme_path,
        "# Project\n\nMaster branch changes\n\n## Updates\nAdded documentation",
    )?;
    repo.add(&["README.md"])?;
    let master_conflict_commit = repo.commit("Update README from master")?;
    println!("   Master commit: {}", master_conflict_commit);

    // Attempt merge (will have conflicts)
    println!("\n3. Attempting merge (will have conflicts)...");
    let merge_status = repo.merge("feature/conflict")?;

    match merge_status {
        MergeStatus::Conflicts(files) => {
            println!("   ⚠️  Merge conflicts detected!");
            println!("   Conflicted files:");
            for file in &files {
                println!("     - {}", file.display());
            }

            // Check merge in progress
            if repo.merge_in_progress()? {
                println!("   ✓ Merge in progress status detected");
            }

            // Show conflict markers in file
            println!("\n4. Conflict markers in README.md:");
            let content = fs::read_to_string(&readme_path)?;
            for (i, line) in content.lines().enumerate() {
                if line.starts_with("<<<<<<< ")
                    || line.starts_with("======= ")
                    || line.starts_with(">>>>>>> ")
                {
                    println!("     {}: {} <-- conflict marker", i + 1, line);
                } else {
                    println!("     {}: {}", i + 1, line);
                }
            }

            // Abort the merge
            println!("\n5. Aborting merge...");
            repo.abort_merge()?;
            println!("   ✓ Merge aborted successfully");

            // Verify merge is no longer in progress
            if !repo.merge_in_progress()? {
                println!("   ✓ Repository is back to clean state");
            }
        }
        _ => println!("   Unexpected merge result: {:?}", merge_status),
    }

    Ok(())
}

impl Repository

pub fn add_remote(&self, name: &str, url: &str) -> Result<()>

Add a new remote to the repository

Arguments

• name - The name for the remote (e.g., “origin”)
• url - The URL for the remote repository

Example

use rustic_git::Repository;
use std::{env, fs};

let test_path = env::temp_dir().join("remote_add_test");
if test_path.exists() {
    fs::remove_dir_all(&test_path).unwrap();
}

let repo = Repository::init(&test_path, false)?;
repo.add_remote("origin", "https://github.com/user/repo.git")?;

// Clean up
fs::remove_dir_all(&test_path).unwrap();

Examples found in repository

examples/remote_operations.rs (line 57)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn remove_remote(&self, name: &str) -> Result<()>

Remove a remote from the repository

Arguments

• name - The name of the remote to remove

Example

use rustic_git::Repository;
use std::{env, fs};

let test_path = env::temp_dir().join("remote_remove_test");
if test_path.exists() {
    fs::remove_dir_all(&test_path).unwrap();
}

let repo = Repository::init(&test_path, false)?;
repo.add_remote("origin", "https://github.com/user/repo.git")?;
repo.remove_remote("origin")?;

// Clean up
fs::remove_dir_all(&test_path).unwrap();

Examples found in repository

examples/remote_operations.rs (line 193)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn rename_remote(&self, old_name: &str, new_name: &str) -> Result<()>

Rename a remote

Arguments

• old_name - The current name of the remote
• new_name - The new name for the remote

Example

use rustic_git::Repository;
use std::{env, fs};

let test_path = env::temp_dir().join("remote_rename_test");
if test_path.exists() {
    fs::remove_dir_all(&test_path).unwrap();
}

let repo = Repository::init(&test_path, false)?;
repo.add_remote("origin", "https://github.com/user/repo.git")?;
repo.rename_remote("origin", "upstream")?;

// Clean up
fs::remove_dir_all(&test_path).unwrap();

Examples found in repository

examples/remote_operations.rs (line 91)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn get_remote_url(&self, name: &str) -> Result<String>

Get the URL for a specific remote

Arguments

• name - The name of the remote

Returns

The fetch URL for the remote

Example

use rustic_git::Repository;
use std::{env, fs};

let test_path = env::temp_dir().join("remote_url_test");
if test_path.exists() {
    fs::remove_dir_all(&test_path).unwrap();
}

let repo = Repository::init(&test_path, false)?;
let url = "https://github.com/user/repo.git";
repo.add_remote("origin", url)?;
let fetched_url = repo.get_remote_url("origin")?;
assert_eq!(fetched_url, url);

// Clean up
fs::remove_dir_all(&test_path).unwrap();

Examples found in repository

examples/remote_operations.rs (line 82)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn list_remotes(&self) -> Result<RemoteList>

List all remotes in the repository

Returns

A RemoteList containing all remotes with their URLs

Example

use rustic_git::Repository;
use std::{env, fs};

let test_path = env::temp_dir().join("remote_list_test");
if test_path.exists() {
    fs::remove_dir_all(&test_path).unwrap();
}

let repo = Repository::init(&test_path, false)?;
repo.add_remote("origin", "https://github.com/user/repo.git")?;
repo.add_remote("upstream", "https://github.com/original/repo.git")?;

let remotes = repo.list_remotes()?;
assert_eq!(remotes.len(), 2);
assert!(remotes.find("origin").is_some());
assert!(remotes.find("upstream").is_some());

// Clean up
fs::remove_dir_all(&test_path).unwrap();

Examples found in repository

examples/remote_operations.rs (line 48)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn fetch(&self, remote: &str) -> Result<()>

Fetch changes from a remote repository

Arguments

• remote - The name of the remote to fetch from

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
repo.fetch("origin")?;

Examples found in repository

examples/remote_operations.rs (line 116)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn fetch_with_options( &self, remote: &str, options: FetchOptions, ) -> Result<()>

Fetch changes from a remote repository with custom options

Arguments

• remote - The name of the remote to fetch from
• options - Fetch options to customize the operation

Example

use rustic_git::{Repository, FetchOptions};

let repo = Repository::open(".")?;
let options = FetchOptions::new().with_prune().with_tags();
repo.fetch_with_options("origin", options)?;

Examples found in repository

examples/remote_operations.rs (line 123)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn push(&self, remote: &str, branch: &str) -> Result<()>

Push changes to a remote repository

Arguments

• remote - The name of the remote to push to
• branch - The name of the branch to push

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
repo.push("origin", "main")?;

Examples found in repository

examples/remote_operations.rs (line 139)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn push_with_options( &self, remote: &str, branch: &str, options: PushOptions, ) -> Result<()>

Push changes to a remote repository with custom options

Arguments

• remote - The name of the remote to push to
• branch - The name of the branch to push
• options - Push options to customize the operation

Example

use rustic_git::{Repository, PushOptions};

let repo = Repository::open(".")?;
let options = PushOptions::new().with_set_upstream();
repo.push_with_options("origin", "main", options)?;

Examples found in repository

examples/remote_operations.rs (line 146)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

pub fn clone<P: AsRef<Path>>(url: &str, path: P) -> Result<Repository>

Clone a remote repository to a local path

Arguments

• url - The URL of the remote repository to clone
• path - The local path where the repository should be cloned

Returns

A Repository instance pointing to the cloned repository

Example

use rustic_git::Repository;

let repo = Repository::clone("https://github.com/user/repo.git", "./local-repo")?;

Examples found in repository

examples/remote_operations.rs (line 167)

fn main() -> Result<()> {
    println!("Rustic Git - Remote Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_remote_example");
    let repo_path = base_path.join("main_repo");
    let clone_path = base_path.join("cloned_repo");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Setup ===\n");

    // Initialize repository
    println!("Initializing repository for remote demonstrations...");
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized at: {}", repo_path.display());

    // Create initial commit so we have something to work with
    fs::write(
        repo_path.join("README.md"),
        "# Remote Operations Demo\n\nDemonstrating rustic-git remote management capabilities.",
    )?;
    repo.add(&["README.md"])?;
    repo.commit("Initial commit for remote operations demo")?;
    println!("Created initial commit\n");

    println!("=== Basic Remote Management ===\n");

    // Check initial remote state
    println!("Checking initial remote state:");
    let remotes = repo.list_remotes()?;
    println!("   Initial remotes count: {}", remotes.len());
    if remotes.is_empty() {
        println!("   No remotes configured (as expected)");
    }
    println!();

    // Add remotes
    println!("Adding remotes...");
    repo.add_remote("origin", "https://github.com/user/demo-repo.git")?;
    println!("   Added 'origin' remote");

    repo.add_remote("upstream", "https://github.com/original/demo-repo.git")?;
    println!("   Added 'upstream' remote");

    repo.add_remote("fork", "git@github.com:user/fork-repo.git")?;
    println!("   Added 'fork' remote (SSH URL)");
    println!();

    // List remotes
    println!("Listing all remotes:");
    let remotes = repo.list_remotes()?;
    println!("   Total remotes: {}", remotes.len());

    for remote in remotes.iter() {
        println!("   {} -> {}", remote.name, remote.fetch_url);
        if let Some(push_url) = &remote.push_url {
            println!("     Push URL: {}", push_url);
        }
    }
    println!();

    // Get specific remote URLs
    println!("Getting specific remote URLs:");
    let origin_url = repo.get_remote_url("origin")?;
    println!("   Origin URL: {}", origin_url);

    let upstream_url = repo.get_remote_url("upstream")?;
    println!("   Upstream URL: {}", upstream_url);
    println!();

    // Rename a remote
    println!("Renaming 'fork' remote to 'my-fork'...");
    repo.rename_remote("fork", "my-fork")?;
    println!("   Remote renamed successfully");

    // Verify rename
    let remotes = repo.list_remotes()?;
    let renamed_remote = remotes.find("my-fork");
    match renamed_remote {
        Some(remote) => println!(
            "   Found renamed remote: {} -> {}",
            remote.name, remote.fetch_url
        ),
        None => println!("   Error: Could not find renamed remote"),
    }

    // Verify old name is gone
    if remotes.find("fork").is_none() {
        println!("   Confirmed: old 'fork' remote no longer exists");
    }
    println!();

    println!("=== Remote Operations with Options ===\n");

    // Demonstrate fetch options
    println!("Fetch operations (simulated - no actual network calls):");
    println!("   Basic fetch from origin:");
    match repo.fetch("origin") {
        Ok(_) => println!("     ✓ Fetch completed successfully"),
        Err(e) => println!("     ⚠ Fetch failed (expected): {}", e),
    }

    println!("   Fetch with options (prune + tags):");
    let fetch_options = FetchOptions::new().with_prune().with_tags();
    match repo.fetch_with_options("origin", fetch_options) {
        Ok(_) => println!("     ✓ Fetch with options completed successfully"),
        Err(e) => println!("     ⚠ Fetch with options failed (expected): {}", e),
    }

    println!("   Fetch all remotes:");
    let fetch_all_options = FetchOptions::new().with_all_remotes();
    match repo.fetch_with_options("", fetch_all_options) {
        Ok(_) => println!("     ✓ Fetch all completed successfully"),
        Err(e) => println!("     ⚠ Fetch all failed (expected): {}", e),
    }
    println!();

    // Demonstrate push options
    println!("Push operations (simulated - no actual network calls):");
    println!("   Basic push to origin:");
    match repo.push("origin", "main") {
        Ok(_) => println!("     ✓ Push completed successfully"),
        Err(e) => println!("     ⚠ Push failed (expected): {}", e),
    }

    println!("   Push with upstream tracking:");
    let push_options = PushOptions::new().with_set_upstream();
    match repo.push_with_options("origin", "main", push_options) {
        Ok(_) => println!("     ✓ Push with upstream completed successfully"),
        Err(e) => println!("     ⚠ Push with upstream failed (expected): {}", e),
    }

    println!("   Force push with tags:");
    let force_push_options = PushOptions::new().with_force().with_tags();
    match repo.push_with_options("my-fork", "feature-branch", force_push_options) {
        Ok(_) => println!("     ✓ Force push with tags completed successfully"),
        Err(e) => println!("     ⚠ Force push with tags failed (expected): {}", e),
    }
    println!();

    println!("=== Clone Operations ===\n");

    // Note: We can't actually clone from the URLs we added since they're fake,
    // but we can demonstrate the API and show how it would work
    println!("Clone operation demonstration:");
    println!("   Attempting to clone a repository...");

    // This will fail since the URL doesn't exist, but demonstrates the API
    match Repository::clone("https://github.com/nonexistent/fake-repo.git", &clone_path) {
        Ok(_repo) => {
            println!("     ✓ Clone completed successfully");
            println!("     Cloned repository location: {}", clone_path.display());
        }
        Err(e) => {
            println!("     ⚠ Clone failed (expected for demo): {}", e);
            println!("     In real usage, provide a valid repository URL");
        }
    }
    println!();

    println!("=== Error Handling and Edge Cases ===\n");

    // Test error cases
    println!("Testing error conditions:");

    // Try to get URL for non-existent remote
    println!("   Getting URL for non-existent remote:");
    match repo.get_remote_url("nonexistent") {
        Ok(url) => println!("     Unexpected success: {}", url),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to remove non-existent remote
    println!("   Removing non-existent remote:");
    match repo.remove_remote("nonexistent") {
        Ok(_) => println!("     Unexpected success"),
        Err(e) => println!("     ✓ Expected error: {}", e),
    }

    // Try to add duplicate remote
    println!("   Adding duplicate remote:");
    match repo.add_remote("origin", "https://github.com/duplicate/repo.git") {
        Ok(_) => println!("     Unexpected success (git allows URL changes)"),
        Err(e) => println!("     Error: {}", e),
    }
    println!();

    println!("=== Remote Cleanup Operations ===\n");

    // Remove remotes one by one
    println!("Removing remotes:");

    println!("   Removing 'upstream' remote...");
    repo.remove_remote("upstream")?;

    println!("   Removing 'my-fork' remote...");
    repo.remove_remote("my-fork")?;

    println!("   Removing 'origin' remote...");
    repo.remove_remote("origin")?;

    // Verify all remotes are gone
    let final_remotes = repo.list_remotes()?;
    println!("   Final remote count: {}", final_remotes.len());

    if final_remotes.is_empty() {
        println!("   ✓ All remotes successfully removed");
    } else {
        println!("   ⚠ Some remotes still remain:");
        for remote in final_remotes.iter() {
            println!("     - {}", remote.name);
        }
    }
    println!();

    println!("=== Advanced Remote Information ===\n");

    // Re-add a remote for advanced operations demo
    repo.add_remote("demo", "https://github.com/demo/advanced-repo.git")?;

    // Show comprehensive remote information
    let remotes = repo.list_remotes()?;
    for remote in remotes.iter() {
        println!("Remote Details:");
        println!("   Name: {}", remote.name);
        println!("   Fetch URL: {}", remote.fetch_url);
        println!("   Push URL: {}", remote.push_url());
        println!("   Uses separate push URL: {}", remote.push_url.is_some());

        // Validate URL format
        if remote.fetch_url.starts_with("https://") {
            println!("   Protocol: HTTPS");
        } else if remote.fetch_url.starts_with("git@") {
            println!("   Protocol: SSH");
        } else if remote.fetch_url.starts_with("git://") {
            println!("   Protocol: Git");
        } else {
            println!("   Protocol: Other/Local");
        }
    }
    println!();

    println!("=== Summary ===\n");

    println!("Remote operations demonstration completed!");
    println!("  Repository: {}", repo_path.display());

    let final_remotes = repo.list_remotes()?;
    println!("  Final remotes configured: {}", final_remotes.len());

    for remote in final_remotes.iter() {
        println!("    - {} ({})", remote.name, remote.fetch_url);
    }

    println!("\nOperations demonstrated:");
    println!("  ✓ Adding remotes with different URL formats");
    println!("  ✓ Listing and inspecting remotes");
    println!("  ✓ Getting specific remote URLs");
    println!("  ✓ Renaming remotes");
    println!("  ✓ Removing remotes");
    println!("  ✓ Fetch operations with options");
    println!("  ✓ Push operations with options");
    println!("  ✓ Clone API demonstration");
    println!("  ✓ Error handling for invalid operations");
    println!("  ✓ Remote information analysis");

    // Clean up
    println!("\nCleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Remote operations example completed!");

    Ok(())
}

impl Repository

pub fn reset_soft(&self, commit: &str) -> Result<()>

Perform a soft reset to the specified commit.

Moves HEAD to the specified commit but keeps both the index and working directory unchanged. Previously staged changes remain staged.

Arguments

• commit - The commit hash, reference, or “HEAD~N” to reset to

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/reset_operations.rs (line 75)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

fn demonstrate_file_resets(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating File-Specific Resets ---\n");

    // Create some files and stage them
    println!("1. Creating and staging multiple files...");

    let file_a = temp_dir.join("fileA.txt");
    let file_b = temp_dir.join("fileB.txt");

    fs::write(&file_a, "Content A")?;
    fs::write(&file_b, "Content B")?;

    repo.add(&["fileA.txt", "fileB.txt"])?;
    println!("   Staged fileA.txt and fileB.txt");

    show_repo_state(repo)?;

    // Reset a single file (using existing reset_file from files.rs)
    println!("\n2. Resetting single file (fileA.txt)...");
    repo.reset_file("fileA.txt")?;

    println!("   After resetting fileA.txt:");
    show_repo_state(repo)?;
    println!("   Note: fileA.txt is unstaged, fileB.txt remains staged");

    // Demonstrate HEAD reset (unstage all changes)
    println!("\n3. Performing mixed reset to HEAD (unstage all)...");
    repo.reset_mixed("HEAD")?;

    println!("   After reset HEAD:");
    show_repo_state(repo)?;
    println!("   Note: All staged changes are now unstaged");

    Ok(())
}

fn demonstrate_error_handling(repo: &Repository) -> Result<()> {
    println!("\n--- Demonstrating Error Handling ---\n");

    // Try to reset to invalid commit
    println!("1. Attempting reset to invalid commit hash...");
    match repo.reset_mixed("invalid_commit_hash") {
        Ok(_) => println!("   Unexpected success!"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Try to reset to non-existent reference
    println!("\n2. Attempting reset to non-existent reference...");
    match repo.reset_soft("nonexistent-branch") {
        Ok(_) => println!("   Unexpected success!"),
        Err(e) => println!("   Expected error: {}", e),
    }

    println!("\n   Error handling works correctly!");
    Ok(())
}

pub fn reset_mixed(&self, commit: &str) -> Result<()>

Perform a mixed reset to the specified commit (default reset behavior).

Moves HEAD to the specified commit and resets the index to match, but leaves the working directory unchanged. Previously staged changes become unstaged but remain in the working directory.

Arguments

• commit - The commit hash, reference, or “HEAD~N” to reset to

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/reset_operations.rs (line 86)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

fn demonstrate_file_resets(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating File-Specific Resets ---\n");

    // Create some files and stage them
    println!("1. Creating and staging multiple files...");

    let file_a = temp_dir.join("fileA.txt");
    let file_b = temp_dir.join("fileB.txt");

    fs::write(&file_a, "Content A")?;
    fs::write(&file_b, "Content B")?;

    repo.add(&["fileA.txt", "fileB.txt"])?;
    println!("   Staged fileA.txt and fileB.txt");

    show_repo_state(repo)?;

    // Reset a single file (using existing reset_file from files.rs)
    println!("\n2. Resetting single file (fileA.txt)...");
    repo.reset_file("fileA.txt")?;

    println!("   After resetting fileA.txt:");
    show_repo_state(repo)?;
    println!("   Note: fileA.txt is unstaged, fileB.txt remains staged");

    // Demonstrate HEAD reset (unstage all changes)
    println!("\n3. Performing mixed reset to HEAD (unstage all)...");
    repo.reset_mixed("HEAD")?;

    println!("   After reset HEAD:");
    show_repo_state(repo)?;
    println!("   Note: All staged changes are now unstaged");

    Ok(())
}

fn demonstrate_error_handling(repo: &Repository) -> Result<()> {
    println!("\n--- Demonstrating Error Handling ---\n");

    // Try to reset to invalid commit
    println!("1. Attempting reset to invalid commit hash...");
    match repo.reset_mixed("invalid_commit_hash") {
        Ok(_) => println!("   Unexpected success!"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Try to reset to non-existent reference
    println!("\n2. Attempting reset to non-existent reference...");
    match repo.reset_soft("nonexistent-branch") {
        Ok(_) => println!("   Unexpected success!"),
        Err(e) => println!("   Expected error: {}", e),
    }

    println!("\n   Error handling works correctly!");
    Ok(())
}

pub fn reset_hard(&self, commit: &str) -> Result<()>

Perform a hard reset to the specified commit.

Moves HEAD to the specified commit and resets both the index and working directory to match. WARNING: This discards all uncommitted changes permanently.

Arguments

• commit - The commit hash, reference, or “HEAD~N” to reset to

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/reset_operations.rs (line 82)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

pub fn reset_with_mode(&self, commit: &str, mode: ResetMode) -> Result<()>

Perform a reset with the specified mode.

This is a flexible method that allows you to specify the reset mode explicitly.

Arguments

• commit - The commit hash, reference, or “HEAD~N” to reset to
• mode - The reset mode (Soft, Mixed, or Hard)

Returns

A Result indicating success or a GitError if the operation fails.

Examples found in repository

examples/reset_operations.rs (line 111)

fn demonstrate_reset_modes(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("--- Demonstrating Reset Modes ---\n");

    // Create initial commits
    println!("1. Creating initial commits...");

    // First commit
    let file1_path = temp_dir.join("file1.txt");
    fs::write(&file1_path, "Initial content")?;
    repo.add(&["file1.txt"])?;
    let first_commit = repo.commit("Initial commit")?;
    println!("   Created first commit: {}", first_commit);

    // Second commit
    let file2_path = temp_dir.join("file2.txt");
    fs::write(&file2_path, "Second file content")?;
    repo.add(&["file2.txt"])?;
    let second_commit = repo.commit("Add file2.txt")?;
    println!("   Created second commit: {}", second_commit);

    // Third commit
    fs::write(&file1_path, "Modified content")?;
    repo.add(&["file1.txt"])?;
    let third_commit = repo.commit("Modify file1.txt")?;
    println!("   Created third commit: {}", third_commit);

    // Show current status
    println!("\n2. Current repository state:");
    show_repo_state(repo)?;

    // Demonstrate soft reset
    println!("\n3. Performing soft reset to second commit...");
    repo.reset_soft(&second_commit.to_string())?;

    println!("   After soft reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are still staged, working directory unchanged");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate mixed reset (default)
    println!("\n4. Performing mixed reset to second commit...");
    repo.reset_mixed(&second_commit.to_string())?;

    println!("   After mixed reset:");
    show_repo_state(repo)?;
    println!("   Note: Changes are unstaged but preserved in working directory");

    // Reset back to third commit for next demonstration
    repo.reset_hard(&third_commit.to_string())?;

    // Demonstrate hard reset
    println!("\n5. Performing hard reset to first commit...");
    repo.reset_hard(&first_commit.to_string())?;

    println!("   After hard reset:");
    show_repo_state(repo)?;
    println!("   Note: All changes discarded, working directory matches commit");

    // Demonstrate reset_with_mode for flexibility
    println!("\n6. Using reset_with_mode for explicit control...");

    // Recreate second commit for demo
    fs::write(&file2_path, "Recreated second file")?;
    repo.add(&["file2.txt"])?;
    let _new_commit = repo.commit("Recreate file2.txt")?;

    repo.reset_with_mode(&first_commit.to_string(), ResetMode::Mixed)?;
    println!("   Used ResetMode::Mixed explicitly");
    show_repo_state(repo)?;

    Ok(())
}

impl Repository

pub fn stash_list(&self) -> Result<StashList>

List all stashes in the repository

Returns a StashList containing all stashes sorted by recency (most recent first).

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let stashes = repo.stash_list()?;

println!("Found {} stashes:", stashes.len());
for stash in stashes.iter() {
    println!("  {}: {}", stash.index, stash.message);
}

Examples found in repository

examples/stash_operations.rs (line 152)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_save(&self, message: &str) -> Result<Stash>

Save current changes to a new stash with a message

This is equivalent to git stash push -m "message".

Arguments

• message - A descriptive message for the stash

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let stash = repo.stash_save("Work in progress on feature X")?;
println!("Created stash: {}", stash.message);

Examples found in repository

examples/stash_operations.rs (line 88)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_push(&self, message: &str, options: StashOptions) -> Result<Stash>

Create a stash with advanced options

Arguments

• message - A descriptive message for the stash
• options - Stash creation options

Example

use rustic_git::{Repository, StashOptions};

let repo = Repository::open(".")?;

// Stash including untracked files
let options = StashOptions::new()
    .with_untracked()
    .with_keep_index();
let stash = repo.stash_push("WIP with untracked files", options)?;

Examples found in repository

examples/stash_operations.rs (lines 123-126)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_apply( &self, index: usize, options: StashApplyOptions, ) -> Result<()>

Apply a stash without removing it from the stash list

Arguments

• index - The stash index to apply (0 is most recent)
• options - Apply options

Example

use rustic_git::{Repository, StashApplyOptions};

let repo = Repository::open(".")?;
let options = StashApplyOptions::new().with_index();
repo.stash_apply(0, options)?; // Apply most recent stash

Examples found in repository

examples/stash_operations.rs (line 209)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_pop(&self, index: usize, options: StashApplyOptions) -> Result<()>

Apply a stash and remove it from the stash list

Arguments

• index - The stash index to pop (0 is most recent)
• options - Apply options

Example

use rustic_git::{Repository, StashApplyOptions};

let repo = Repository::open(".")?;
repo.stash_pop(0, StashApplyOptions::new())?; // Pop most recent stash

Examples found in repository

examples/stash_operations.rs (line 240)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_show(&self, index: usize) -> Result<String>

Show the contents of a stash

Arguments

• index - The stash index to show (0 is most recent)

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let stash_info = repo.stash_show(0)?;
println!("Stash contents:\n{}", stash_info);

Examples found in repository

examples/stash_operations.rs (line 198)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_drop(&self, index: usize) -> Result<()>

Delete a specific stash

Arguments

• index - The stash index to delete

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
repo.stash_drop(1)?; // Delete second most recent stash

Examples found in repository

examples/stash_operations.rs (line 295)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

pub fn stash_clear(&self) -> Result<()>

Clear all stashes

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
repo.stash_clear()?; // Remove all stashes

Examples found in repository

examples/stash_operations.rs (line 309)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

impl Repository

pub fn status(&self) -> Result<GitStatus>

Get the status of the repository.

Returns

A Result containing the GitStatus or a GitError.

Examples found in repository

examples/reset_operations.rs (line 176)

fn show_repo_state(repo: &Repository) -> Result<()> {
    let status = repo.status()?;

    let staged_count = status.staged_files().count();
    let unstaged_count = status.unstaged_files().count();
    let untracked_count = status.untracked_entries().count();

    println!("   Repository state:");
    println!("     - Staged files: {}", staged_count);
    println!("     - Modified files: {}", unstaged_count);
    println!("     - Untracked files: {}", untracked_count);

    if staged_count > 0 {
        println!("     - Staged:");
        for file in status.staged_files().take(5) {
            println!("       * {}", file.path.display());
        }
    }

    if unstaged_count > 0 {
        println!("     - Modified:");
        for file in status.unstaged_files().take(5) {
            println!("       * {}", file.path.display());
        }
    }

    if untracked_count > 0 {
        println!("     - Untracked:");
        for file in status.untracked_entries().take(5) {
            println!("       * {}", file.path.display());
        }
    }

    Ok(())
}

examples/merge_operations.rs (line 278)

fn demonstrate_merge_status_and_abort(repo: &Repository, temp_dir: &std::path::Path) -> Result<()> {
    println!("\n--- Demonstrating Merge Status and Options ---\n");

    // Create a simple feature branch
    println!("1. Creating simple feature branch...");
    repo.checkout_new("feature/simple", None)?;

    let simple_path = temp_dir.join("simple.txt");
    fs::write(&simple_path, "Simple feature content")?;
    repo.add(&["simple.txt"])?;
    repo.commit("Add simple feature")?;

    // Switch back to master
    let branches = repo.branches()?;
    let master_branch = branches.find("master").unwrap();
    repo.checkout(master_branch)?;

    // Test merge with different options
    println!("\n2. Testing merge with custom options...");
    let options = MergeOptions::new()
        .with_fast_forward(FastForwardMode::Auto)
        .with_message("Integrate simple feature".to_string());

    let merge_status = repo.merge_with_options("feature/simple", options)?;

    match merge_status {
        MergeStatus::FastForward(hash) => {
            println!("   ✓ Fast-forward merge completed: {}", hash);
        }
        MergeStatus::Success(hash) => {
            println!("   ✓ Merge commit created: {}", hash);
        }
        MergeStatus::UpToDate => {
            println!("   ✓ Already up to date");
        }
        MergeStatus::Conflicts(_) => {
            println!("   ⚠️  Unexpected conflicts");
        }
    }

    // Show final repository state
    println!("\n3. Final repository state:");
    let status = repo.status()?;
    println!(
        "   Working directory clean: {}",
        status.staged_files().count() == 0 && status.unstaged_files().count() == 0
    );

    let commits = repo.recent_commits(5)?;
    println!("   Recent commits:");
    for (i, commit) in commits.iter().enumerate() {
        println!(
            "     {}: {} - {}",
            i + 1,
            commit.hash.short(),
            commit.message.subject
        );
    }

    Ok(())
}

examples/error_handling.rs (line 132)

fn demonstrate_file_operation_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("File Operation Error Scenarios:\n");

    // Set up a valid repository first
    let repo = Repository::init(repo_path, false)?;

    // Create some test files
    fs::write(repo_path.join("test.txt"), "Test content")?;
    repo.add(&["test.txt"])?;
    repo.commit("Initial commit")?;

    // 1. Adding non-existent files
    println!("1. Attempting to add non-existent files:");
    match repo.add(&["does_not_exist.txt", "also_missing.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git add failed because files don't exist");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Mixed valid and invalid files
    println!("\n2. Adding mix of valid and invalid files:");
    fs::write(repo_path.join("valid.txt"), "Valid file")?;

    match repo.add(&["valid.txt", "invalid.txt"]) {
        Ok(_) => {
            println!("   Partially succeeded - some Git versions allow this");
            // Check what actually got staged
            let status = repo.status()?;
            println!("   {} files staged despite error", status.entries.len());
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Entire add operation failed due to invalid file");

            // Try recovery: add valid files individually
            println!("   Recovery: Adding valid files individually...");
            match repo.add(&["valid.txt"]) {
                Ok(_) => println!("      Successfully added valid.txt"),
                Err(e) => println!("      Recovery failed: {:?}", e),
            }
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate Git command related errors
fn demonstrate_git_command_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Git Command Error Scenarios:\n");

    let repo = Repository::open(repo_path)?;

    // 1. Empty commit (no staged changes)
    println!("1. Attempting commit with no staged changes:");
    match repo.commit("Empty commit attempt") {
        Ok(hash) => {
            println!("   Unexpectedly succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commits");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git requires changes to commit (normal behavior)");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Commit with problematic message
    println!("\n2. Testing commit message edge cases:");

    // Stage a file for testing
    fs::write(
        repo_path.join("commit_test.txt"),
        "Content for commit testing",
    )?;
    repo.add(&["commit_test.txt"])?;

    // Very long commit message
    let very_long_message = "A ".repeat(1000) + "very long commit message";
    match repo.commit(&very_long_message) {
        Ok(hash) => {
            println!("   Long commit message succeeded: {}", hash.short());
            println!("   Git handled the long message fine");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   Long commit message failed: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError with long message: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error recovery patterns
fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

examples/basic_usage.rs (line 59)

fn main() -> Result<()> {
    println!("Rustic Git - Basic Usage Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_basic_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Create some example files
    println!("Creating example files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello from rustic-git example!");
}
"#,
    )?;

    fs::write(
        repo_path.join("src/lib.rs"),
        "// Library code goes here\npub fn hello() -> &'static str {\n    \"Hello, World!\"\n}\n",
    )?;

    println!("Created 3 files: README.md, src/main.rs, src/lib.rs\n");

    // Check repository status
    println!("Checking repository status...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("   Repository is clean (no changes)");
    } else {
        println!("   Repository has changes:");
        println!("   Unstaged files: {}", status.unstaged_files().count());
        println!("   Untracked files: {}", status.untracked_entries().count());

        // Show untracked files
        for entry in status.untracked_entries() {
            println!("      - {}", entry.path.display());
        }
    }
    println!();

    // Stage specific files first
    println!("Staging files...");

    // Stage README.md first
    repo.add(&["README.md"])?;
    println!("Staged README.md");

    // Stage all remaining files
    repo.add_all()?;
    println!("Staged all remaining files");

    // Check status after staging
    let status_after_staging = repo.status()?;
    println!("\nStatus after staging:");
    if status_after_staging.is_clean() {
        println!("   Repository is clean (all changes staged)");
    } else {
        println!(
            "   Files staged for commit: {}",
            status_after_staging.entries.len()
        );
        for entry in &status_after_staging.entries {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }
    println!();

    // Create a commit
    println!("Creating commit...");
    let hash = repo.commit("Initial commit: Add project structure and basic files")?;

    println!("Commit created successfully!");
    println!("   Full hash: {}", hash);
    println!("   Short hash: {}", hash.short());
    println!();

    // Verify final status
    println!("Final repository status:");
    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("   Repository is clean - all changes committed!");
    } else {
        println!("   Repository still has uncommitted changes");
    }
    println!();

    // Clean up
    println!("Cleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Example completed successfully!");

    Ok(())
}

examples/repository_operations.rs (line 71)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_repo_example");
    let regular_repo_path = base_path.join("regular");
    let bare_repo_path = base_path.join("bare");
    let nonexistent_path = base_path.join("nonexistent");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Initialization ===\n");

    // 1. Initialize a regular repository
    println!("Initializing regular repository...");
    let regular_repo = Repository::init(&regular_repo_path, false)?;
    println!(
        "Regular repository created at: {}",
        regular_repo_path.display()
    );
    println!("   Repository path: {:?}", regular_repo.repo_path());

    // Verify it's a git repo by checking for .git directory
    if regular_repo_path.join(".git").exists() {
        println!("   .git directory found");
    }
    println!();

    // 2. Initialize a bare repository
    println!("Initializing bare repository...");
    let bare_repo = Repository::init(&bare_repo_path, true)?;
    println!("Bare repository created at: {}", bare_repo_path.display());
    println!("   Repository path: {:?}", bare_repo.repo_path());

    // Verify bare repo structure (has HEAD, objects, etc. directly)
    if bare_repo_path.join("HEAD").exists() {
        println!("   HEAD file found (bare repository structure)");
    }
    if bare_repo_path.join("objects").exists() {
        println!("   objects directory found");
    }
    println!();

    println!("=== Repository Opening ===\n");

    // 3. Open the existing regular repository
    println!("Opening existing regular repository...");
    match Repository::open(&regular_repo_path) {
        Ok(opened_repo) => {
            println!("Successfully opened regular repository");
            println!("   Repository path: {:?}", opened_repo.repo_path());

            // Test that we can perform operations on the opened repo
            let status = opened_repo.status()?;
            println!("   Repository status: {} files", status.entries.len());
        }
        Err(e) => {
            println!("Failed to open regular repository: {:?}", e);
        }
    }
    println!();

    // 4. Open the existing bare repository
    println!("Opening existing bare repository...");
    match Repository::open(&bare_repo_path) {
        Ok(opened_bare) => {
            println!("Successfully opened bare repository");
            println!("   Repository path: {:?}", opened_bare.repo_path());

            // Note: status operations might behave differently on bare repos
            match opened_bare.status() {
                Ok(status) => println!("   Bare repository status: {} files", status.entries.len()),
                Err(e) => println!(
                    "   Note: Status check on bare repo failed (expected): {:?}",
                    e
                ),
            }
        }
        Err(e) => {
            println!("Failed to open bare repository: {:?}", e);
        }
    }
    println!();

    println!("=== Error Handling ===\n");

    // 5. Try to open a non-existent repository
    println!("Attempting to open non-existent repository...");
    match Repository::open(&nonexistent_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening non-existent repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    // 6. Try to open a regular file as a repository
    let fake_repo_path = base_path.join("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("Attempting to open regular file as repository...");
    match Repository::open(&fake_repo_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening regular file as repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    println!("=== Repository Information ===\n");

    // 7. Compare regular vs bare repository information
    println!("Comparing repository types:");

    let regular_path = regular_repo.repo_path();
    let bare_path = bare_repo.repo_path();

    println!("   Regular repo path: {:?}", regular_path);
    println!("   Bare repo path: {:?}", bare_path);

    // Show directory contents
    if let Ok(entries) = fs::read_dir(regular_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Regular repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }

    if let Ok(entries) = fs::read_dir(bare_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Bare repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }
    println!();

    // Clean up
    println!("Cleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Repository operations example completed!");

    Ok(())
}

examples/status_checking.rs (line 32)

fn main() -> Result<()> {
    println!("Rustic Git - Status Checking Example\n");

    let repo_path = env::temp_dir().join("rustic_git_status_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    // Initialize repository
    println!("Setting up repository for status demonstration...");
    let repo = Repository::init(&repo_path, false)?;

    println!("=== Clean Repository Status ===\n");

    // Check initial status (should be clean)
    let status = repo.status()?;
    println!("Initial repository status:");
    display_status_summary(&status);
    println!();

    println!("=== Creating Files with Different States ===\n");

    // Create various types of files to demonstrate different statuses
    println!("Creating test files...");

    // Create some files that will be untracked
    fs::write(repo_path.join("untracked1.txt"), "This file is untracked")?;
    fs::write(repo_path.join("untracked2.txt"), "Another untracked file")?;

    // Create a .gitignore to demonstrate ignored files
    fs::write(repo_path.join(".gitignore"), "*.log\n*.tmp\n/temp/\n")?;

    // Create files that will be ignored
    fs::write(repo_path.join("debug.log"), "Log file content")?;
    fs::write(repo_path.join("cache.tmp"), "Temporary file")?;
    fs::create_dir_all(repo_path.join("temp"))?;
    fs::write(repo_path.join("temp/data.txt"), "Temp data")?;

    println!("Created test files");

    // Check status after creating untracked files
    println!("\nStatus after creating untracked files:");
    let status_untracked = repo.status()?;
    display_status_summary(&status_untracked);
    display_detailed_status(&status_untracked);
    println!();

    println!("=== Staging Files to Show 'Added' Status ===\n");

    // Stage some files to show "Added" status
    repo.add(&["untracked1.txt", ".gitignore"])?;
    println!("Staged untracked1.txt and .gitignore");

    let status_added = repo.status()?;
    println!("\nStatus after staging files:");
    display_status_summary(&status_added);
    display_detailed_status(&status_added);
    println!();

    println!("=== Creating Initial Commit ===\n");

    // Commit the staged files so we can demonstrate modified/deleted states
    let _hash = repo.commit("Initial commit with basic files")?;
    println!("Created initial commit");

    let status_after_commit = repo.status()?;
    println!("\nStatus after commit:");
    display_status_summary(&status_after_commit);
    if !status_after_commit.is_clean() {
        display_detailed_status(&status_after_commit);
    }
    println!();

    println!("=== Modifying Files to Show 'Modified' Status ===\n");

    // Modify existing tracked files
    fs::write(
        repo_path.join("untracked1.txt"),
        "This file has been MODIFIED!",
    )?;
    fs::write(
        repo_path.join(".gitignore"),
        "*.log\n*.tmp\n/temp/\n# Added comment\n",
    )?;
    println!("Modified untracked1.txt and .gitignore");

    let status_modified = repo.status()?;
    println!("\nStatus after modifying files:");
    display_status_summary(&status_modified);
    display_detailed_status(&status_modified);
    println!();

    println!("=== Demonstrating All Status Query Methods ===\n");

    // Stage one of the modified files to show mixed states
    repo.add(&["untracked1.txt"])?;
    println!("Staged untracked1.txt (now shows as Added)");

    let status_mixed = repo.status()?;
    println!("\nMixed status demonstration:");
    display_status_summary(&status_mixed);

    // Demonstrate different query methods
    println!("\nUsing different status query methods:");

    println!("   All files ({} total):", status_mixed.entries.len());
    for entry in &status_mixed.entries {
        println!(
            "      Index {:?}, Worktree {:?}: {}",
            entry.index_status,
            entry.worktree_status,
            entry.path.display()
        );
    }

    // Query by specific status
    let unstaged_files: Vec<_> = status_mixed.unstaged_files().collect();
    if !unstaged_files.is_empty() {
        println!("\n   Unstaged files ({}):", unstaged_files.len());
        for entry in &unstaged_files {
            println!("      - {}", entry.path.display());
        }
    }

    let untracked_files: Vec<_> = status_mixed.untracked_entries().collect();
    if !untracked_files.is_empty() {
        println!("\n   Untracked files ({}):", untracked_files.len());
        for entry in &untracked_files {
            println!("      - {}", entry.path.display());
        }
    }

    // Query by IndexStatus enum
    let added_files: Vec<_> = status_mixed
        .files_with_index_status(IndexStatus::Added)
        .collect();
    if !added_files.is_empty() {
        println!("\n   Added files ({}):", added_files.len());
        for entry in &added_files {
            println!("      - {}", entry.path.display());
        }
    }

    println!();

    println!("=== File Status Filtering Examples ===\n");

    // Demonstrate filtering capabilities
    println!("Filtering examples:");

    // Count files by status
    let mut index_status_counts = std::collections::HashMap::new();
    let mut worktree_status_counts = std::collections::HashMap::new();

    for entry in &status_mixed.entries {
        if !matches!(entry.index_status, IndexStatus::Clean) {
            *index_status_counts
                .entry(format!("{:?}", entry.index_status))
                .or_insert(0) += 1;
        }
        if !matches!(entry.worktree_status, WorktreeStatus::Clean) {
            *worktree_status_counts
                .entry(format!("{:?}", entry.worktree_status))
                .or_insert(0) += 1;
        }
    }

    println!("   Index status counts:");
    for (status, count) in &index_status_counts {
        println!("      {}: {} files", status, count);
    }

    println!("   Worktree status counts:");
    for (status, count) in &worktree_status_counts {
        println!("      {}: {} files", status, count);
    }

    // Filter for specific patterns
    let txt_files: Vec<_> = status_mixed
        .entries
        .iter()
        .filter(|entry| entry.path.to_string_lossy().ends_with(".txt"))
        .collect();

    if !txt_files.is_empty() {
        println!("\n   .txt files:");
        for entry in txt_files {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }

    println!();

    println!("=== Repository State Checking ===\n");

    println!("Repository state summary:");
    println!("   Total files tracked: {}", status_mixed.entries.len());
    println!("   Is clean: {}", status_mixed.is_clean());
    println!("   Has changes: {}", status_mixed.has_changes());

    if status_mixed.has_changes() {
        println!("   Repository needs attention!");

        let unstaged_count = status_mixed.unstaged_files().count();
        if unstaged_count > 0 {
            println!("      - {} files need to be staged", unstaged_count);
        }

        let untracked_count = status_mixed.untracked_entries().count();
        if untracked_count > 0 {
            println!("      - {} untracked files to consider", untracked_count);
        }

        let staged_count = status_mixed.staged_files().count();
        if staged_count > 0 {
            println!("      - {} files ready to commit", staged_count);
        }
    }

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Status checking example completed!");

    Ok(())
}

Additional examples can be found in:

• examples/staging_operations.rs
• examples/commit_workflows.rs
• examples/stash_operations.rs
• examples/file_lifecycle_operations.rs

impl Repository

pub fn tags(&self) -> Result<TagList>

List all tags in the repository

Returns a TagList containing all tags sorted by name.

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let tags = repo.tags()?;

println!("Found {} tags:", tags.len());
for tag in tags.iter() {
    println!("  {} ({}) -> {}", tag.name, tag.tag_type, tag.hash.short());
}

Examples found in repository

examples/tag_operations.rs (line 129)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

pub fn create_tag(&self, name: &str, target: Option<&Hash>) -> Result<Tag>

Create a lightweight tag pointing to the current HEAD or specified commit

Arguments

• name - The name of the tag to create
• target - Optional commit hash to tag (defaults to HEAD)

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;

// Tag current HEAD
let tag = repo.create_tag("v1.0.0", None)?;

// Tag specific commit
let commits = repo.recent_commits(1)?;
if let Some(commit) = commits.iter().next() {
    let tag = repo.create_tag("v0.9.0", Some(&commit.hash))?;
}

Examples found in repository

examples/tag_operations.rs (line 71)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

pub fn create_tag_with_options( &self, name: &str, target: Option<&Hash>, options: TagOptions, ) -> Result<Tag>

Create a tag with custom options

Arguments

• name - The name of the tag to create
• target - Optional commit hash to tag (defaults to HEAD)
• options - Tag creation options

Example

use rustic_git::{Repository, TagOptions};

let repo = Repository::open(".")?;

// Create annotated tag with message
let options = TagOptions::new()
    .with_message("Release version 1.0.0".to_string());
let tag = repo.create_tag_with_options("v1.0.0", None, options)?;

// Create and force overwrite existing tag
let options = TagOptions::new().with_force();
let tag = repo.create_tag_with_options("latest", None, options)?;

Examples found in repository

examples/tag_operations.rs (line 92)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

pub fn delete_tag(&self, name: &str) -> Result<()>

Delete a tag

Arguments

• name - The name of the tag to delete

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
repo.delete_tag("v0.1.0")?;

Examples found in repository

examples/tag_operations.rs (line 258)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

pub fn show_tag(&self, name: &str) -> Result<Tag>

Show detailed information about a specific tag

Arguments

• name - The name of the tag to show

Example

use rustic_git::Repository;

let repo = Repository::open(".")?;
let tag = repo.show_tag("v1.0.0")?;

println!("Tag: {} ({})", tag.name, tag.tag_type);
println!("Commit: {}", tag.hash.short());
if let Some(message) = &tag.message {
    println!("Message: {}", message);
}

Examples found in repository

examples/tag_operations.rs (line 200)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

impl Repository

pub fn ensure_git() -> Result<()>

Ensure that Git is available in the system PATH.

This function checks if the git command is available in the system PATH. The result is cached, so subsequent calls are very fast. If Git is not found, it returns a GitError::CommandFailed with an appropriate error message.

Returns

A Result containing either Ok(()) if Git is available or a GitError.

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open an existing Git repository at the specified path.

Arguments

• path - The path to an existing Git repository.

Returns

A Result containing either the opened Repository instance or a GitError.

Examples found in repository

examples/error_handling.rs (line 49)

fn demonstrate_repository_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Repository Error Scenarios:\n");

    // 1. Opening non-existent repository
    println!("1. Attempting to open non-existent repository:");
    match Repository::open("/definitely/does/not/exist") {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
            println!("   This typically happens when the path doesn't exist");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git command failed - path exists but isn't a repo");
        }
    }

    // 2. Opening a file as a repository
    let fake_repo_path = repo_path.with_extension("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("\n2. Attempting to open regular file as repository:");
    match Repository::open(&fake_repo_path) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git recognized the path but it's not a repository");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    fs::remove_file(&fake_repo_path)?;

    // 3. Initializing repository with invalid path
    println!("\n3. Attempting to initialize repository with problematic path:");

    // Try to initialize in a location that might cause issues
    match Repository::init("/root/definitely_no_permission", false) {
        Ok(_) => println!("   Unexpectedly succeeded (you might be running as root!)"),
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
            println!("   Likely a permission issue");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git init command failed");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate file operation related errors
fn demonstrate_file_operation_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("File Operation Error Scenarios:\n");

    // Set up a valid repository first
    let repo = Repository::init(repo_path, false)?;

    // Create some test files
    fs::write(repo_path.join("test.txt"), "Test content")?;
    repo.add(&["test.txt"])?;
    repo.commit("Initial commit")?;

    // 1. Adding non-existent files
    println!("1. Attempting to add non-existent files:");
    match repo.add(&["does_not_exist.txt", "also_missing.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git add failed because files don't exist");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Mixed valid and invalid files
    println!("\n2. Adding mix of valid and invalid files:");
    fs::write(repo_path.join("valid.txt"), "Valid file")?;

    match repo.add(&["valid.txt", "invalid.txt"]) {
        Ok(_) => {
            println!("   Partially succeeded - some Git versions allow this");
            // Check what actually got staged
            let status = repo.status()?;
            println!("   {} files staged despite error", status.entries.len());
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Entire add operation failed due to invalid file");

            // Try recovery: add valid files individually
            println!("   Recovery: Adding valid files individually...");
            match repo.add(&["valid.txt"]) {
                Ok(_) => println!("      Successfully added valid.txt"),
                Err(e) => println!("      Recovery failed: {:?}", e),
            }
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate Git command related errors
fn demonstrate_git_command_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Git Command Error Scenarios:\n");

    let repo = Repository::open(repo_path)?;

    // 1. Empty commit (no staged changes)
    println!("1. Attempting commit with no staged changes:");
    match repo.commit("Empty commit attempt") {
        Ok(hash) => {
            println!("   Unexpectedly succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commits");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git requires changes to commit (normal behavior)");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Commit with problematic message
    println!("\n2. Testing commit message edge cases:");

    // Stage a file for testing
    fs::write(
        repo_path.join("commit_test.txt"),
        "Content for commit testing",
    )?;
    repo.add(&["commit_test.txt"])?;

    // Very long commit message
    let very_long_message = "A ".repeat(1000) + "very long commit message";
    match repo.commit(&very_long_message) {
        Ok(hash) => {
            println!("   Long commit message succeeded: {}", hash.short());
            println!("   Git handled the long message fine");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   Long commit message failed: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError with long message: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error recovery patterns
fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error propagation strategies
fn demonstrate_error_propagation_strategies(base_path: &std::path::Path) -> Result<()> {
    println!("Error Propagation Strategies:\n");

    // Strategy 1: Early return with ?
    println!("1. Early Return Strategy (using ?):");
    match workflow_with_early_return(base_path) {
        Ok(message) => println!("      Workflow completed: {}", message),
        Err(e) => println!("      Workflow failed early: {:?}", e),
    }

    // Strategy 2: Collect all errors
    println!("\n2. Error Collection Strategy:");
    let results = workflow_with_error_collection(base_path);

    let successful = results.iter().filter(|r| r.is_ok()).count();
    let failed = results.iter().filter(|r| r.is_err()).count();

    println!(
        "      Operations: {} succeeded, {} failed",
        successful, failed
    );

    for (i, result) in results.iter().enumerate() {
        match result {
            Ok(msg) => println!("         Step {}: {}", i + 1, msg),
            Err(e) => println!("         Step {}: {:?}", i + 1, e),
        }
    }

    // Strategy 3: Error context enrichment
    println!("\n3. Error Context Strategy:");
    match workflow_with_context(base_path) {
        Ok(message) => println!("      Contextual workflow: {}", message),
        Err(e) => println!("      Contextual workflow failed: {:?}", e),
    }

    println!();
    Ok(())
}

/// Workflow that returns early on first error
fn workflow_with_early_return(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("early_return_test");

    // This will propagate any error immediately
    let repo = Repository::init(&repo_path, false)?;

    fs::write(repo_path.join("file1.txt"), "Content 1")?;
    repo.add(&["file1.txt"])?;

    let hash = repo.commit("Early return workflow commit")?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Completed with commit {}", hash.short()))
}

/// Workflow that collects all errors instead of failing fast
fn workflow_with_error_collection(base_path: &std::path::Path) -> Vec<Result<String>> {
    let repo_path = base_path.join("error_collection_test");
    let mut results = Vec::new();

    // Step 1: Initialize repo
    results.push(Repository::init(&repo_path, false).map(|_| "Repository initialized".to_string()));

    // Step 2: Add files (some may fail)
    let files_to_create = ["good.txt", "another_good.txt"];

    for file in &files_to_create {
        results.push(
            fs::write(repo_path.join(file), "Content")
                .map_err(GitError::from)
                .map(|_| format!("Created {}", file)),
        );
    }

    // Step 3: Try to add files (continue even if repo init failed)
    if let Ok(repo) = Repository::open(&repo_path) {
        results.push(
            repo.add(&files_to_create)
                .map(|_| "Files added to staging".to_string()),
        );

        results.push(
            repo.commit("Error collection workflow")
                .map(|hash| format!("Committed: {}", hash.short())),
        );
    } else {
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for adding files".to_string(),
        )));
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for commit".to_string(),
        )));
    }

    // Cleanup (don't add to results as it's not part of main workflow)
    let _ = fs::remove_dir_all(&repo_path);

    results
}

examples/repository_operations.rs (line 65)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_repo_example");
    let regular_repo_path = base_path.join("regular");
    let bare_repo_path = base_path.join("bare");
    let nonexistent_path = base_path.join("nonexistent");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Initialization ===\n");

    // 1. Initialize a regular repository
    println!("Initializing regular repository...");
    let regular_repo = Repository::init(&regular_repo_path, false)?;
    println!(
        "Regular repository created at: {}",
        regular_repo_path.display()
    );
    println!("   Repository path: {:?}", regular_repo.repo_path());

    // Verify it's a git repo by checking for .git directory
    if regular_repo_path.join(".git").exists() {
        println!("   .git directory found");
    }
    println!();

    // 2. Initialize a bare repository
    println!("Initializing bare repository...");
    let bare_repo = Repository::init(&bare_repo_path, true)?;
    println!("Bare repository created at: {}", bare_repo_path.display());
    println!("   Repository path: {:?}", bare_repo.repo_path());

    // Verify bare repo structure (has HEAD, objects, etc. directly)
    if bare_repo_path.join("HEAD").exists() {
        println!("   HEAD file found (bare repository structure)");
    }
    if bare_repo_path.join("objects").exists() {
        println!("   objects directory found");
    }
    println!();

    println!("=== Repository Opening ===\n");

    // 3. Open the existing regular repository
    println!("Opening existing regular repository...");
    match Repository::open(&regular_repo_path) {
        Ok(opened_repo) => {
            println!("Successfully opened regular repository");
            println!("   Repository path: {:?}", opened_repo.repo_path());

            // Test that we can perform operations on the opened repo
            let status = opened_repo.status()?;
            println!("   Repository status: {} files", status.entries.len());
        }
        Err(e) => {
            println!("Failed to open regular repository: {:?}", e);
        }
    }
    println!();

    // 4. Open the existing bare repository
    println!("Opening existing bare repository...");
    match Repository::open(&bare_repo_path) {
        Ok(opened_bare) => {
            println!("Successfully opened bare repository");
            println!("   Repository path: {:?}", opened_bare.repo_path());

            // Note: status operations might behave differently on bare repos
            match opened_bare.status() {
                Ok(status) => println!("   Bare repository status: {} files", status.entries.len()),
                Err(e) => println!(
                    "   Note: Status check on bare repo failed (expected): {:?}",
                    e
                ),
            }
        }
        Err(e) => {
            println!("Failed to open bare repository: {:?}", e);
        }
    }
    println!();

    println!("=== Error Handling ===\n");

    // 5. Try to open a non-existent repository
    println!("Attempting to open non-existent repository...");
    match Repository::open(&nonexistent_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening non-existent repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    // 6. Try to open a regular file as a repository
    let fake_repo_path = base_path.join("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("Attempting to open regular file as repository...");
    match Repository::open(&fake_repo_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening regular file as repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    println!("=== Repository Information ===\n");

    // 7. Compare regular vs bare repository information
    println!("Comparing repository types:");

    let regular_path = regular_repo.repo_path();
    let bare_path = bare_repo.repo_path();

    println!("   Regular repo path: {:?}", regular_path);
    println!("   Bare repo path: {:?}", bare_path);

    // Show directory contents
    if let Ok(entries) = fs::read_dir(regular_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Regular repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }

    if let Ok(entries) = fs::read_dir(bare_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Bare repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }
    println!();

    // Clean up
    println!("Cleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Repository operations example completed!");

    Ok(())
}

pub fn init<P: AsRef<Path>>(path: P, bare: bool) -> Result<Self>

Initialize a new Git repository at the specified path.

Arguments

• path - The path where the repository should be initialized.
• bare - Whether the repository should be bare or not.

Returns

A Result containing either the initialized Repository instance or a GitError.

Examples found in repository

examples/reset_operations.rs (line 27)

fn main() -> Result<()> {
    println!("=== Reset Operations Demo ===\n");

    // Create a temporary directory for our example
    let temp_dir = env::temp_dir().join("rustic_git_reset_demo");

    // Clean up if exists
    if temp_dir.exists() {
        fs::remove_dir_all(&temp_dir)?;
    }

    println!("Working in temporary directory: {:?}\n", temp_dir);

    // Initialize a new repository
    let repo = Repository::init(&temp_dir, false)?;

    // Configure user for commits
    repo.config().set_user("Example User", "example@test.com")?;

    demonstrate_reset_modes(&repo, &temp_dir)?;
    demonstrate_file_resets(&repo, &temp_dir)?;
    demonstrate_error_handling(&repo)?;

    println!("\n=== Reset Operations Demo Complete ===");

    // Clean up
    fs::remove_dir_all(&temp_dir)?;
    Ok(())
}

examples/merge_operations.rs (line 28)

fn main() -> Result<()> {
    println!("=== Merge Operations Demo ===\n");

    // Create a temporary directory for our example
    let temp_dir = env::temp_dir().join("rustic_git_merge_demo");

    // Clean up if exists
    if temp_dir.exists() {
        fs::remove_dir_all(&temp_dir)?;
    }

    println!("Working in temporary directory: {:?}\n", temp_dir);

    // Initialize a new repository
    let repo = Repository::init(&temp_dir, false)?;

    // Configure user for commits
    repo.config().set_user("Example User", "example@test.com")?;

    demonstrate_fast_forward_merge(&repo, &temp_dir)?;
    demonstrate_no_fast_forward_merge(&repo, &temp_dir)?;
    demonstrate_merge_conflicts(&repo, &temp_dir)?;
    demonstrate_merge_status_and_abort(&repo, &temp_dir)?;

    println!("\n=== Merge Operations Demo Complete ===");

    // Clean up
    fs::remove_dir_all(&temp_dir)?;
    Ok(())
}

examples/error_handling.rs (line 83)

fn demonstrate_repository_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Repository Error Scenarios:\n");

    // 1. Opening non-existent repository
    println!("1. Attempting to open non-existent repository:");
    match Repository::open("/definitely/does/not/exist") {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
            println!("   This typically happens when the path doesn't exist");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git command failed - path exists but isn't a repo");
        }
    }

    // 2. Opening a file as a repository
    let fake_repo_path = repo_path.with_extension("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("\n2. Attempting to open regular file as repository:");
    match Repository::open(&fake_repo_path) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git recognized the path but it's not a repository");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    fs::remove_file(&fake_repo_path)?;

    // 3. Initializing repository with invalid path
    println!("\n3. Attempting to initialize repository with problematic path:");

    // Try to initialize in a location that might cause issues
    match Repository::init("/root/definitely_no_permission", false) {
        Ok(_) => println!("   Unexpectedly succeeded (you might be running as root!)"),
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
            println!("   Likely a permission issue");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git init command failed");
        }
    }

    println!();
    Ok(())
}

/// Demonstrate file operation related errors
fn demonstrate_file_operation_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("File Operation Error Scenarios:\n");

    // Set up a valid repository first
    let repo = Repository::init(repo_path, false)?;

    // Create some test files
    fs::write(repo_path.join("test.txt"), "Test content")?;
    repo.add(&["test.txt"])?;
    repo.commit("Initial commit")?;

    // 1. Adding non-existent files
    println!("1. Attempting to add non-existent files:");
    match repo.add(&["does_not_exist.txt", "also_missing.txt"]) {
        Ok(_) => println!("   Unexpectedly succeeded"),
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git add failed because files don't exist");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Mixed valid and invalid files
    println!("\n2. Adding mix of valid and invalid files:");
    fs::write(repo_path.join("valid.txt"), "Valid file")?;

    match repo.add(&["valid.txt", "invalid.txt"]) {
        Ok(_) => {
            println!("   Partially succeeded - some Git versions allow this");
            // Check what actually got staged
            let status = repo.status()?;
            println!("   {} files staged despite error", status.entries.len());
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Entire add operation failed due to invalid file");

            // Try recovery: add valid files individually
            println!("   Recovery: Adding valid files individually...");
            match repo.add(&["valid.txt"]) {
                Ok(_) => println!("      Successfully added valid.txt"),
                Err(e) => println!("      Recovery failed: {:?}", e),
            }
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate Git command related errors
fn demonstrate_git_command_errors(repo_path: &std::path::Path) -> Result<()> {
    println!("Git Command Error Scenarios:\n");

    let repo = Repository::open(repo_path)?;

    // 1. Empty commit (no staged changes)
    println!("1. Attempting commit with no staged changes:");
    match repo.commit("Empty commit attempt") {
        Ok(hash) => {
            println!("   Unexpectedly succeeded: {}", hash.short());
            println!("   Some Git configurations allow empty commits");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   CommandFailed caught: {}", msg);
            println!("   Git requires changes to commit (normal behavior)");
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError caught: {}", msg);
        }
    }

    // 2. Commit with problematic message
    println!("\n2. Testing commit message edge cases:");

    // Stage a file for testing
    fs::write(
        repo_path.join("commit_test.txt"),
        "Content for commit testing",
    )?;
    repo.add(&["commit_test.txt"])?;

    // Very long commit message
    let very_long_message = "A ".repeat(1000) + "very long commit message";
    match repo.commit(&very_long_message) {
        Ok(hash) => {
            println!("   Long commit message succeeded: {}", hash.short());
            println!("   Git handled the long message fine");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("   Long commit message failed: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("   IoError with long message: {}", msg);
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error recovery patterns
fn demonstrate_error_recovery_patterns(repo_path: &std::path::Path) -> Result<()> {
    println!("Error Recovery Patterns:\n");

    let repo = Repository::open(repo_path)?;

    // Pattern 1: Retry with different approach
    println!("1. Retry Pattern - Graceful degradation:");

    // Try to add specific files, fall back to add_all on failure
    let files_to_add = ["missing1.txt", "missing2.txt", "missing3.txt"];

    println!("   Attempting to add specific files...");
    match repo.add(&files_to_add) {
        Ok(_) => println!("      Specific files added successfully"),
        Err(e) => {
            println!("      Specific files failed: {:?}", e);
            println!("      Falling back to add_all()...");

            match repo.add_all() {
                Ok(_) => {
                    let status = repo.status()?;
                    println!(
                        "      add_all() succeeded, {} files staged",
                        status.entries.len()
                    );
                }
                Err(fallback_error) => {
                    println!("      Fallback also failed: {:?}", fallback_error);
                }
            }
        }
    }

    // Pattern 2: Partial success handling
    println!("\n2. Partial Success Pattern:");

    // Create some files with known issues
    fs::write(repo_path.join("good1.txt"), "Good file 1")?;
    fs::write(repo_path.join("good2.txt"), "Good file 2")?;
    // Don't create bad1.txt - it will be missing

    let mixed_files = ["good1.txt", "bad1.txt", "good2.txt"];

    println!("   Attempting to add mixed valid/invalid files...");
    match repo.add(&mixed_files) {
        Ok(_) => println!("      All files added (unexpected success)"),
        Err(GitError::CommandFailed(msg)) => {
            println!("      Batch add failed: {}", msg);
            println!("      Recovery: Adding files individually...");

            let mut successful_adds = 0;
            let mut failed_adds = 0;

            for file in &mixed_files {
                match repo.add(&[file]) {
                    Ok(_) => {
                        successful_adds += 1;
                        println!("         Added: {}", file);
                    }
                    Err(_) => {
                        failed_adds += 1;
                        println!("         Failed: {}", file);
                    }
                }
            }

            println!(
                "      Results: {} succeeded, {} failed",
                successful_adds, failed_adds
            );
        }
        Err(GitError::IoError(msg)) => {
            println!("      IoError during batch add: {}", msg);
        }
    }

    // Pattern 3: Status checking before operations
    println!("\n3. Preventive Pattern - Check before operation:");

    println!("   Checking repository status before commit...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("      Repository is clean - no commit needed");
    } else {
        println!("      Repository has {} changes", status.entries.len());

        // Show what would be committed
        for entry in &status.entries {
            println!(
                "         Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }

        // Safe commit since we know there are changes
        match repo.commit("Commit after status check") {
            Ok(hash) => println!("      Safe commit succeeded: {}", hash.short()),
            Err(e) => println!("      Even safe commit failed: {:?}", e),
        }
    }

    println!();
    Ok(())
}

/// Demonstrate error propagation strategies
fn demonstrate_error_propagation_strategies(base_path: &std::path::Path) -> Result<()> {
    println!("Error Propagation Strategies:\n");

    // Strategy 1: Early return with ?
    println!("1. Early Return Strategy (using ?):");
    match workflow_with_early_return(base_path) {
        Ok(message) => println!("      Workflow completed: {}", message),
        Err(e) => println!("      Workflow failed early: {:?}", e),
    }

    // Strategy 2: Collect all errors
    println!("\n2. Error Collection Strategy:");
    let results = workflow_with_error_collection(base_path);

    let successful = results.iter().filter(|r| r.is_ok()).count();
    let failed = results.iter().filter(|r| r.is_err()).count();

    println!(
        "      Operations: {} succeeded, {} failed",
        successful, failed
    );

    for (i, result) in results.iter().enumerate() {
        match result {
            Ok(msg) => println!("         Step {}: {}", i + 1, msg),
            Err(e) => println!("         Step {}: {:?}", i + 1, e),
        }
    }

    // Strategy 3: Error context enrichment
    println!("\n3. Error Context Strategy:");
    match workflow_with_context(base_path) {
        Ok(message) => println!("      Contextual workflow: {}", message),
        Err(e) => println!("      Contextual workflow failed: {:?}", e),
    }

    println!();
    Ok(())
}

/// Workflow that returns early on first error
fn workflow_with_early_return(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("early_return_test");

    // This will propagate any error immediately
    let repo = Repository::init(&repo_path, false)?;

    fs::write(repo_path.join("file1.txt"), "Content 1")?;
    repo.add(&["file1.txt"])?;

    let hash = repo.commit("Early return workflow commit")?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Completed with commit {}", hash.short()))
}

/// Workflow that collects all errors instead of failing fast
fn workflow_with_error_collection(base_path: &std::path::Path) -> Vec<Result<String>> {
    let repo_path = base_path.join("error_collection_test");
    let mut results = Vec::new();

    // Step 1: Initialize repo
    results.push(Repository::init(&repo_path, false).map(|_| "Repository initialized".to_string()));

    // Step 2: Add files (some may fail)
    let files_to_create = ["good.txt", "another_good.txt"];

    for file in &files_to_create {
        results.push(
            fs::write(repo_path.join(file), "Content")
                .map_err(GitError::from)
                .map(|_| format!("Created {}", file)),
        );
    }

    // Step 3: Try to add files (continue even if repo init failed)
    if let Ok(repo) = Repository::open(&repo_path) {
        results.push(
            repo.add(&files_to_create)
                .map(|_| "Files added to staging".to_string()),
        );

        results.push(
            repo.commit("Error collection workflow")
                .map(|hash| format!("Committed: {}", hash.short())),
        );
    } else {
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for adding files".to_string(),
        )));
        results.push(Err(GitError::CommandFailed(
            "Could not open repo for commit".to_string(),
        )));
    }

    // Cleanup (don't add to results as it's not part of main workflow)
    let _ = fs::remove_dir_all(&repo_path);

    results
}

/// Workflow with enhanced error context
fn workflow_with_context(base_path: &std::path::Path) -> Result<String> {
    let repo_path = base_path.join("context_test");

    // Add context to errors
    let repo = Repository::init(&repo_path, false).inspect_err(|_e| {
        eprintln!(
            "Context: Failed to initialize repository at {}",
            repo_path.display()
        );
    })?;

    // Create file with context
    fs::write(repo_path.join("context_file.txt"), "Content with context").map_err(|e| {
        eprintln!("Context: Failed to create context_file.txt");
        GitError::from(e)
    })?;

    // Add with context
    repo.add(&["context_file.txt"]).inspect_err(|_e| {
        eprintln!("Context: Failed to stage context_file.txt");
    })?;

    // Commit with context
    let hash = repo.commit("Context workflow commit").inspect_err(|_e| {
        eprintln!("Context: Failed to create commit");
    })?;

    // Clean up
    fs::remove_dir_all(&repo_path)?;

    Ok(format!("Context workflow completed: {}", hash.short()))
}

examples/basic_usage.rs (line 30)

fn main() -> Result<()> {
    println!("Rustic Git - Basic Usage Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_basic_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Create some example files
    println!("Creating example files...");
    fs::create_dir_all(repo_path.join("src"))?;

    fs::write(
        repo_path.join("README.md"),
        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
    )?;

    fs::write(
        repo_path.join("src/main.rs"),
        r#"fn main() {
    println!("Hello from rustic-git example!");
}
"#,
    )?;

    fs::write(
        repo_path.join("src/lib.rs"),
        "// Library code goes here\npub fn hello() -> &'static str {\n    \"Hello, World!\"\n}\n",
    )?;

    println!("Created 3 files: README.md, src/main.rs, src/lib.rs\n");

    // Check repository status
    println!("Checking repository status...");
    let status = repo.status()?;

    if status.is_clean() {
        println!("   Repository is clean (no changes)");
    } else {
        println!("   Repository has changes:");
        println!("   Unstaged files: {}", status.unstaged_files().count());
        println!("   Untracked files: {}", status.untracked_entries().count());

        // Show untracked files
        for entry in status.untracked_entries() {
            println!("      - {}", entry.path.display());
        }
    }
    println!();

    // Stage specific files first
    println!("Staging files...");

    // Stage README.md first
    repo.add(&["README.md"])?;
    println!("Staged README.md");

    // Stage all remaining files
    repo.add_all()?;
    println!("Staged all remaining files");

    // Check status after staging
    let status_after_staging = repo.status()?;
    println!("\nStatus after staging:");
    if status_after_staging.is_clean() {
        println!("   Repository is clean (all changes staged)");
    } else {
        println!(
            "   Files staged for commit: {}",
            status_after_staging.entries.len()
        );
        for entry in &status_after_staging.entries {
            println!(
                "      Index {:?}, Worktree {:?}: {}",
                entry.index_status,
                entry.worktree_status,
                entry.path.display()
            );
        }
    }
    println!();

    // Create a commit
    println!("Creating commit...");
    let hash = repo.commit("Initial commit: Add project structure and basic files")?;

    println!("Commit created successfully!");
    println!("   Full hash: {}", hash);
    println!("   Short hash: {}", hash.short());
    println!();

    // Verify final status
    println!("Final repository status:");
    let final_status = repo.status()?;
    if final_status.is_clean() {
        println!("   Repository is clean - all changes committed!");
    } else {
        println!("   Repository still has uncommitted changes");
    }
    println!();

    // Clean up
    println!("Cleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Example completed successfully!");

    Ok(())
}

examples/branch_operations.rs (line 13)

fn main() -> Result<()> {
    let test_path = env::temp_dir().join("rustic_git_branch_example");

    // Clean up if exists
    if test_path.exists() {
        fs::remove_dir_all(&test_path).unwrap();
    }

    // Create a test repository
    let repo = Repository::init(&test_path, false)?;
    println!("Created repository at: {}", test_path.display());

    // Create initial commit so we have a valid HEAD
    fs::write(test_path.join("README.md"), "# Branch Operations Demo\n").unwrap();
    repo.add(&["README.md"])?;
    repo.commit("Initial commit")?;
    println!("Created initial commit");

    // List all branches
    let branches = repo.branches()?;
    println!("\n=== Initial Branches ===");
    for branch in branches.iter() {
        println!("  {}", branch);
    }

    // Get current branch
    if let Some(current) = repo.current_branch()? {
        println!(
            "\nCurrent branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Create new branches
    println!("\n=== Creating Branches ===");
    let feature_branch = repo.create_branch("feature/new-api", None)?;
    println!("Created branch: {}", feature_branch.name);

    let bugfix_branch = repo.create_branch("bugfix/issue-123", Some("HEAD"))?;
    println!("Created branch: {}", bugfix_branch.name);

    // List branches again
    let branches = repo.branches()?;
    println!("\n=== After Creating Branches ===");
    for branch in branches.local() {
        println!("  {} (local)", branch);
    }

    // Create and checkout a new branch
    println!("\n=== Creating and Checking Out Branch ===");
    let dev_branch = repo.checkout_new("develop", None)?;
    println!("Created and checked out: {}", dev_branch.name);

    // Make a commit on the new branch
    fs::write(test_path.join("feature.txt"), "New feature code\n").unwrap();
    repo.add(&["feature.txt"])?;
    repo.commit("Add new feature")?;
    println!("Made commit on develop branch");

    // Show current branch after checkout
    if let Some(current) = repo.current_branch()? {
        println!(
            "Now on branch: {} ({})",
            current.name,
            current.commit_hash.short()
        );
    }

    // Switch back to master branch
    let main_branch = branches.find("master").unwrap().clone();
    repo.checkout(&main_branch)?;
    println!("\nSwitched back to master branch");

    // List all branches with details
    let final_branches = repo.branches()?;
    println!("\n=== Final Branch List ===");
    println!("Total branches: {}", final_branches.len());
    println!("Local branches: {}", final_branches.local_count());

    for branch in final_branches.iter() {
        let marker = if branch.is_current { "*" } else { " " };
        let branch_type = if branch.is_local() { "local" } else { "remote" };
        println!(
            "  {}{} ({}) {}",
            marker,
            branch.name,
            branch_type,
            branch.commit_hash.short()
        );

        if let Some(upstream) = &branch.upstream {
            println!("    └── tracks: {}", upstream);
        }
    }

    // Demonstrate branch searching
    println!("\n=== Branch Search Examples ===");

    if let Some(branch) = final_branches.find("develop") {
        println!("Found branch by name: {}", branch.name);
    }

    if let Some(branch) = final_branches.find_by_short_name("new-api") {
        println!("Found branch by short name: {}", branch.name);
    }

    // Demonstrate branch filtering
    println!("\n=== Branch Filtering ===");

    println!("Local branches:");
    for branch in final_branches.local() {
        println!("  - {}", branch.name);
    }

    if final_branches.remote_count() > 0 {
        println!("Remote branches:");
        for branch in final_branches.remote() {
            println!("  - {}", branch.name);
        }
    }

    // Delete a branch (switch away first if it's current)
    println!("\n=== Branch Deletion ===");
    let bugfix = final_branches.find("bugfix/issue-123").unwrap().clone();
    repo.delete_branch(&bugfix, false)?;
    println!("Deleted branch: {}", bugfix.name);

    // Show final state
    let final_branches = repo.branches()?;
    println!("\nFinal branch count: {}", final_branches.len());

    // Clean up
    fs::remove_dir_all(&test_path).unwrap();
    println!("\nCleaned up test repository");

    Ok(())
}

examples/repository_operations.rs (line 33)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_repo_example");
    let regular_repo_path = base_path.join("regular");
    let bare_repo_path = base_path.join("bare");
    let nonexistent_path = base_path.join("nonexistent");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Initialization ===\n");

    // 1. Initialize a regular repository
    println!("Initializing regular repository...");
    let regular_repo = Repository::init(&regular_repo_path, false)?;
    println!(
        "Regular repository created at: {}",
        regular_repo_path.display()
    );
    println!("   Repository path: {:?}", regular_repo.repo_path());

    // Verify it's a git repo by checking for .git directory
    if regular_repo_path.join(".git").exists() {
        println!("   .git directory found");
    }
    println!();

    // 2. Initialize a bare repository
    println!("Initializing bare repository...");
    let bare_repo = Repository::init(&bare_repo_path, true)?;
    println!("Bare repository created at: {}", bare_repo_path.display());
    println!("   Repository path: {:?}", bare_repo.repo_path());

    // Verify bare repo structure (has HEAD, objects, etc. directly)
    if bare_repo_path.join("HEAD").exists() {
        println!("   HEAD file found (bare repository structure)");
    }
    if bare_repo_path.join("objects").exists() {
        println!("   objects directory found");
    }
    println!();

    println!("=== Repository Opening ===\n");

    // 3. Open the existing regular repository
    println!("Opening existing regular repository...");
    match Repository::open(&regular_repo_path) {
        Ok(opened_repo) => {
            println!("Successfully opened regular repository");
            println!("   Repository path: {:?}", opened_repo.repo_path());

            // Test that we can perform operations on the opened repo
            let status = opened_repo.status()?;
            println!("   Repository status: {} files", status.entries.len());
        }
        Err(e) => {
            println!("Failed to open regular repository: {:?}", e);
        }
    }
    println!();

    // 4. Open the existing bare repository
    println!("Opening existing bare repository...");
    match Repository::open(&bare_repo_path) {
        Ok(opened_bare) => {
            println!("Successfully opened bare repository");
            println!("   Repository path: {:?}", opened_bare.repo_path());

            // Note: status operations might behave differently on bare repos
            match opened_bare.status() {
                Ok(status) => println!("   Bare repository status: {} files", status.entries.len()),
                Err(e) => println!(
                    "   Note: Status check on bare repo failed (expected): {:?}",
                    e
                ),
            }
        }
        Err(e) => {
            println!("Failed to open bare repository: {:?}", e);
        }
    }
    println!();

    println!("=== Error Handling ===\n");

    // 5. Try to open a non-existent repository
    println!("Attempting to open non-existent repository...");
    match Repository::open(&nonexistent_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening non-existent repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    // 6. Try to open a regular file as a repository
    let fake_repo_path = base_path.join("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("Attempting to open regular file as repository...");
    match Repository::open(&fake_repo_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening regular file as repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    println!("=== Repository Information ===\n");

    // 7. Compare regular vs bare repository information
    println!("Comparing repository types:");

    let regular_path = regular_repo.repo_path();
    let bare_path = bare_repo.repo_path();

    println!("   Regular repo path: {:?}", regular_path);
    println!("   Bare repo path: {:?}", bare_path);

    // Show directory contents
    if let Ok(entries) = fs::read_dir(regular_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Regular repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }

    if let Ok(entries) = fs::read_dir(bare_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Bare repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }
    println!();

    // Clean up
    println!("Cleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Repository operations example completed!");

    Ok(())
}

Additional examples can be found in:

• examples/config_operations.rs
• examples/status_checking.rs
• examples/staging_operations.rs
• examples/diff_operations.rs
• examples/commit_workflows.rs
• examples/tag_operations.rs
• examples/remote_operations.rs
• examples/commit_history.rs
• examples/stash_operations.rs
• examples/file_lifecycle_operations.rs

pub fn repo_path(&self) -> &Path

Examples found in repository

examples/repository_operations.rs (line 38)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Operations Example\n");

    let base_path = env::temp_dir().join("rustic_git_repo_example");
    let regular_repo_path = base_path.join("regular");
    let bare_repo_path = base_path.join("bare");
    let nonexistent_path = base_path.join("nonexistent");

    // Clean up any previous runs
    if base_path.exists() {
        fs::remove_dir_all(&base_path).expect("Failed to clean up previous example");
    }
    fs::create_dir_all(&base_path)?;

    println!("=== Repository Initialization ===\n");

    // 1. Initialize a regular repository
    println!("Initializing regular repository...");
    let regular_repo = Repository::init(&regular_repo_path, false)?;
    println!(
        "Regular repository created at: {}",
        regular_repo_path.display()
    );
    println!("   Repository path: {:?}", regular_repo.repo_path());

    // Verify it's a git repo by checking for .git directory
    if regular_repo_path.join(".git").exists() {
        println!("   .git directory found");
    }
    println!();

    // 2. Initialize a bare repository
    println!("Initializing bare repository...");
    let bare_repo = Repository::init(&bare_repo_path, true)?;
    println!("Bare repository created at: {}", bare_repo_path.display());
    println!("   Repository path: {:?}", bare_repo.repo_path());

    // Verify bare repo structure (has HEAD, objects, etc. directly)
    if bare_repo_path.join("HEAD").exists() {
        println!("   HEAD file found (bare repository structure)");
    }
    if bare_repo_path.join("objects").exists() {
        println!("   objects directory found");
    }
    println!();

    println!("=== Repository Opening ===\n");

    // 3. Open the existing regular repository
    println!("Opening existing regular repository...");
    match Repository::open(&regular_repo_path) {
        Ok(opened_repo) => {
            println!("Successfully opened regular repository");
            println!("   Repository path: {:?}", opened_repo.repo_path());

            // Test that we can perform operations on the opened repo
            let status = opened_repo.status()?;
            println!("   Repository status: {} files", status.entries.len());
        }
        Err(e) => {
            println!("Failed to open regular repository: {:?}", e);
        }
    }
    println!();

    // 4. Open the existing bare repository
    println!("Opening existing bare repository...");
    match Repository::open(&bare_repo_path) {
        Ok(opened_bare) => {
            println!("Successfully opened bare repository");
            println!("   Repository path: {:?}", opened_bare.repo_path());

            // Note: status operations might behave differently on bare repos
            match opened_bare.status() {
                Ok(status) => println!("   Bare repository status: {} files", status.entries.len()),
                Err(e) => println!(
                    "   Note: Status check on bare repo failed (expected): {:?}",
                    e
                ),
            }
        }
        Err(e) => {
            println!("Failed to open bare repository: {:?}", e);
        }
    }
    println!();

    println!("=== Error Handling ===\n");

    // 5. Try to open a non-existent repository
    println!("Attempting to open non-existent repository...");
    match Repository::open(&nonexistent_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening non-existent repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    // 6. Try to open a regular file as a repository
    let fake_repo_path = base_path.join("fake.txt");
    fs::write(&fake_repo_path, "This is not a git repository")?;

    println!("Attempting to open regular file as repository...");
    match Repository::open(&fake_repo_path) {
        Ok(_repo) => {
            println!("Unexpectedly succeeded opening regular file as repo");
        }
        Err(GitError::CommandFailed(msg)) => {
            println!("Expected error caught: CommandFailed");
            println!("   Error message: {}", msg);
        }
        Err(GitError::IoError(msg)) => {
            println!("Expected error caught: IoError");
            println!("   Error message: {}", msg);
        }
    }
    println!();

    println!("=== Repository Information ===\n");

    // 7. Compare regular vs bare repository information
    println!("Comparing repository types:");

    let regular_path = regular_repo.repo_path();
    let bare_path = bare_repo.repo_path();

    println!("   Regular repo path: {:?}", regular_path);
    println!("   Bare repo path: {:?}", bare_path);

    // Show directory contents
    if let Ok(entries) = fs::read_dir(regular_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Regular repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }

    if let Ok(entries) = fs::read_dir(bare_path) {
        let mut files: Vec<_> = entries.filter_map(|e| e.ok()).collect();
        files.sort_by_key(|e| e.file_name());

        println!("   Bare repo contents:");
        for entry in files {
            if let Some(name) = entry.file_name().to_str() {
                let is_dir = entry.file_type().map(|t| t.is_dir()).unwrap_or(false);
                let marker = if is_dir { "[DIR]" } else { "[FILE]" };
                println!("     {} {}", marker, name);
            }
        }
    }
    println!();

    // Clean up
    println!("Cleaning up example repositories...");
    fs::remove_dir_all(&base_path)?;
    println!("Repository operations example completed!");

    Ok(())
}

pub fn config(&self) -> RepoConfig<'_>

Get a configuration manager for this repository

Returns a RepoConfig instance that can be used to get and set git configuration values for this repository.

Example

use rustic_git::Repository;
use std::env;

let test_path = env::temp_dir().join("test");
let repo = Repository::init(&test_path, false)?;
repo.config().set_user("John Doe", "john@example.com")?;

let (name, email) = repo.config().get_user()?;
assert_eq!(name, "John Doe");
assert_eq!(email, "john@example.com");

Examples found in repository

examples/reset_operations.rs (line 30)

fn main() -> Result<()> {
    println!("=== Reset Operations Demo ===\n");

    // Create a temporary directory for our example
    let temp_dir = env::temp_dir().join("rustic_git_reset_demo");

    // Clean up if exists
    if temp_dir.exists() {
        fs::remove_dir_all(&temp_dir)?;
    }

    println!("Working in temporary directory: {:?}\n", temp_dir);

    // Initialize a new repository
    let repo = Repository::init(&temp_dir, false)?;

    // Configure user for commits
    repo.config().set_user("Example User", "example@test.com")?;

    demonstrate_reset_modes(&repo, &temp_dir)?;
    demonstrate_file_resets(&repo, &temp_dir)?;
    demonstrate_error_handling(&repo)?;

    println!("\n=== Reset Operations Demo Complete ===");

    // Clean up
    fs::remove_dir_all(&temp_dir)?;
    Ok(())
}

examples/merge_operations.rs (line 31)

fn main() -> Result<()> {
    println!("=== Merge Operations Demo ===\n");

    // Create a temporary directory for our example
    let temp_dir = env::temp_dir().join("rustic_git_merge_demo");

    // Clean up if exists
    if temp_dir.exists() {
        fs::remove_dir_all(&temp_dir)?;
    }

    println!("Working in temporary directory: {:?}\n", temp_dir);

    // Initialize a new repository
    let repo = Repository::init(&temp_dir, false)?;

    // Configure user for commits
    repo.config().set_user("Example User", "example@test.com")?;

    demonstrate_fast_forward_merge(&repo, &temp_dir)?;
    demonstrate_no_fast_forward_merge(&repo, &temp_dir)?;
    demonstrate_merge_conflicts(&repo, &temp_dir)?;
    demonstrate_merge_status_and_abort(&repo, &temp_dir)?;

    println!("\n=== Merge Operations Demo Complete ===");

    // Clean up
    fs::remove_dir_all(&temp_dir)?;
    Ok(())
}

examples/config_operations.rs (line 35)

fn main() -> Result<()> {
    println!("Rustic Git - Repository Configuration Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_config_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing new repository at: {}", repo_path.display());

    // Initialize a new repository
    let repo = Repository::init(&repo_path, false)?;

    // ==================== USER CONFIGURATION ====================

    println!("\n[CONFIG] Configuring git user settings...");

    // Set user configuration (convenience method)
    repo.config()
        .set_user("Alice Developer", "alice@example.com")?;
    println!("Set user configuration");

    // Verify user configuration
    let (name, email) = repo.config().get_user()?;
    println!("Current user: {} <{}>", name, email);

    // ==================== GENERAL CONFIGURATION ====================

    println!("\n[CONFIG] Setting repository configuration values...");

    // Set various git configuration values
    repo.config().set("core.autocrlf", "false")?;
    repo.config().set("core.ignorecase", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "simple")?;
    repo.config().set("branch.autosetupmerge", "always")?;

    println!("Set core configuration values");

    // Get and display configuration values
    println!("\n[CONFIG] Current repository configuration:");

    let configs = [
        "core.autocrlf",
        "core.ignorecase",
        "pull.rebase",
        "push.default",
        "branch.autosetupmerge",
    ];

    for config_key in &configs {
        match repo.config().get(config_key) {
            Ok(value) => println!("  {} = {}", config_key, value),
            Err(_) => println!("  {} = <not set>", config_key),
        }
    }

    // ==================== CONFIGURATION WITH COMMITS ====================

    println!("\n[COMMIT] Testing configuration with commit operations...");

    // Create a test file
    let test_file_path = repo_path.join("test.txt");
    fs::write(
        &test_file_path,
        "Hello from rustic-git configuration example!",
    )?;
    println!("Created test file: test.txt");

    // Stage the file
    repo.add(&["test.txt"])?;
    println!("Staged test.txt");

    // Create a commit (this will use our configured user)
    let commit_hash = repo.commit("Add test file with configuration example")?;
    println!("Created commit: {}", commit_hash.short());

    // ==================== CONFIGURATION MODIFICATION ====================

    println!("\n[UPDATE] Modifying configuration values...");

    // Change some configuration values
    repo.config().set("core.autocrlf", "true")?;
    repo.config()
        .set("user.email", "alice.developer@newcompany.com")?;

    println!("Updated configuration values");

    // Display updated values
    let autocrlf = repo.config().get("core.autocrlf")?;
    let (updated_name, updated_email) = repo.config().get_user()?;

    println!("Updated configuration:");
    println!("  core.autocrlf = {}", autocrlf);
    println!("  user: {} <{}>", updated_name, updated_email);

    // ==================== CONFIGURATION REMOVAL ====================

    println!("\n[REMOVE] Removing configuration values...");

    // Remove a configuration value
    repo.config().unset("branch.autosetupmerge")?;
    println!("Removed branch.autosetupmerge");

    // Try to get the removed value (should fail)
    match repo.config().get("branch.autosetupmerge") {
        Ok(value) => println!("Unexpected: branch.autosetupmerge = {}", value),
        Err(_) => println!("Confirmed: branch.autosetupmerge is not set"),
    }

    // ==================== ADVANCED CONFIGURATION ====================

    println!("\n[ADVANCED] Setting advanced configuration...");

    // Set some advanced git configuration
    repo.config().set("diff.tool", "vimdiff")?;
    repo.config().set("merge.tool", "vimdiff")?;
    repo.config().set("alias.st", "status")?;
    repo.config().set("alias.co", "checkout")?;
    repo.config().set("alias.br", "branch")?;
    repo.config().set("alias.ci", "commit")?;

    println!("Set advanced configuration (diff/merge tools and aliases)");

    // Display all custom configuration
    println!("\n[SUMMARY] Complete repository configuration summary:");

    let all_configs = [
        ("User", vec![("user.name", ""), ("user.email", "")]),
        ("Core", vec![("core.autocrlf", ""), ("core.ignorecase", "")]),
        ("Workflow", vec![("pull.rebase", ""), ("push.default", "")]),
        ("Tools", vec![("diff.tool", ""), ("merge.tool", "")]),
        (
            "Aliases",
            vec![
                ("alias.st", ""),
                ("alias.co", ""),
                ("alias.br", ""),
                ("alias.ci", ""),
            ],
        ),
    ];

    for (category, configs) in &all_configs {
        println!("\n  {}:", category);
        for (key, _) in configs {
            match repo.config().get(key) {
                Ok(value) => println!("    {} = {}", key, value),
                Err(_) => println!("    {} = <not set>", key),
            }
        }
    }

    // ==================== PRACTICAL EXAMPLE ====================

    println!("\n[TEAM] Practical example: Setting up repository for a team...");

    // Configure repository for team development
    repo.config().set("user.name", "Team Member")?;
    repo.config().set("user.email", "team@company.com")?;
    repo.config().set("core.autocrlf", "input")?;
    repo.config().set("core.safecrlf", "true")?;
    repo.config().set("pull.rebase", "true")?;
    repo.config().set("push.default", "current")?;
    repo.config().set("init.defaultBranch", "main")?;

    println!("Configured repository for team development");

    // Create another commit with the team configuration
    fs::write(
        repo_path.join("team.md"),
        "# Team Development\n\nThis repository is configured for team development.",
    )?;
    repo.add(&["team.md"])?;
    let team_commit = repo.commit("Add team development documentation")?;

    println!("Created team commit: {}", team_commit.short());

    // Final verification
    let (final_name, final_email) = repo.config().get_user()?;
    println!("\n[FINAL] Final repository configuration:");
    println!("  User: {} <{}>", final_name, final_email);
    println!("  Repository configured for team development workflow");

    // ==================== CLEANUP ====================

    println!("\n[CLEANUP] Cleaning up...");
    fs::remove_dir_all(&repo_path).expect("Failed to clean up example");
    println!("Example completed successfully!");

    Ok(())
}

examples/diff_operations.rs (line 19)

fn main() -> rustic_git::Result<()> {
    println!("Rustic Git - Diff Operations Example\n");

    let repo_path = env::temp_dir().join("rustic_git_diff_example");
    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).ok();
    }
    println!("Working in temporary directory: {}", repo_path.display());

    // Initialize repository
    let repo = Repository::init(&repo_path, false)?;
    println!("Repository initialized successfully\n");

    // Configure git user for commits
    let config = repo.config();
    config.set_user("Test User", "test@example.com")?;

    println!("=== Creating Initial Files ===");

    // Create initial files
    let readme_path = repo_path.join("README.md");
    let src_dir = repo_path.join("src");
    fs::create_dir_all(&src_dir).unwrap();
    let main_path = src_dir.join("main.rs");
    let lib_path = src_dir.join("lib.rs");

    fs::write(
        &readme_path,
        "# Test Project\n\nA sample project for testing diff operations.\n",
    )
    .unwrap();
    fs::write(
        &main_path,
        "fn main() {\n    println!(\"Hello, world!\");\n}\n",
    )
    .unwrap();
    fs::write(
        &lib_path,
        "pub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}\n",
    )
    .unwrap();

    println!("Created initial files: README.md, src/main.rs, src/lib.rs");

    // Stage and commit initial files
    repo.add_all()?;
    let initial_commit = repo.commit("feat: initial commit with basic files")?;
    println!("Initial commit: {}\n", initial_commit.short());

    println!("=== Testing Different Diff Operations ===");

    // Test 1: Diff with no changes (should be empty)
    println!("1. Diff with no changes:");
    let diff = repo.diff()?;
    if diff.is_empty() {
        println!("   ✓ No changes detected (as expected)");
    } else {
        println!("   ✗ Unexpected changes found");
    }
    println!();

    // Test 2: Modify files and show unstaged changes
    println!("2. Creating unstaged changes:");
    fs::write(&readme_path, "# Test Project\n\nA sample project for testing diff operations.\n\n## Features\n- Git operations\n- Diff functionality\n").unwrap();
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");\n}\n").unwrap();

    let diff = repo.diff()?;
    println!("   Unstaged changes found:");
    println!("   Files changed: {}", diff.len());
    for file in diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", diff.stats);
    println!();

    // Test 3: Stage some changes and show staged vs unstaged
    println!("3. Staging README.md and checking staged diff:");
    repo.add(&[&readme_path])?;

    let staged_diff = repo.diff_staged()?;
    println!("   Staged changes:");
    for file in staged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", staged_diff.stats);

    let unstaged_diff = repo.diff()?;
    println!("   Remaining unstaged changes:");
    for file in unstaged_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!("   {}", unstaged_diff.stats);
    println!();

    // Test 4: Diff with options
    println!("4. Using diff options (name-only):");
    let name_only_diff = repo.diff_with_options(&DiffOptions::new().name_only())?;
    println!("   Modified files (name-only):");
    for file in name_only_diff.iter() {
        println!("   - {}", file.path.display());
    }
    println!();

    // Test 5: Diff with file filtering
    println!("5. Diff with path filtering (src/ only):");
    let src_paths = vec![src_dir.clone()];
    let filtered_diff = repo.diff_with_options(&DiffOptions::new().paths(src_paths))?;
    println!("   Changes in src/ directory:");
    for file in filtered_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Stage remaining changes and commit
    repo.add_all()?;
    let second_commit = repo.commit("feat: add features section and improve main function")?;
    println!("Second commit: {}", second_commit.short());

    // Test 6: Diff between commits
    println!("\n6. Diff between commits:");
    let commit_diff = repo.diff_commits(&initial_commit, &second_commit)?;
    println!(
        "   Changes from {} to {}:",
        initial_commit.short(),
        second_commit.short()
    );
    for file in commit_diff.iter() {
        println!(
            "   - {} ({}) +{} -{}",
            file.path.display(),
            file.status,
            file.additions,
            file.deletions
        );
    }
    println!("   {}", commit_diff.stats);
    println!();

    // Test 7: Add a new file and show it in diff
    println!("7. Adding new file and checking diff:");
    let test_path = repo_path.join("test.txt");
    fs::write(
        &test_path,
        "This is a new test file.\nWith multiple lines.\n",
    )
    .unwrap();

    let new_file_diff = repo.diff()?;
    println!("   New file detected:");
    for file in new_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 8: Delete a file and show in diff
    println!("8. Deleting file and checking diff:");
    fs::remove_file(&lib_path).unwrap();

    let deleted_file_diff = repo.diff()?;
    println!("   Changes after file deletion:");
    for file in deleted_file_diff.iter() {
        println!("   - {} ({})", file.path.display(), file.status);
    }
    println!();

    // Test 9: Diff with ignore whitespace options
    println!("9. Testing whitespace options:");

    // Add some whitespace changes
    fs::write(&main_path, "fn main() {\n    println!(\"Hello, world!\");\n    println!(\"Testing diff operations!\");    \n}\n").unwrap();

    let normal_diff = repo.diff()?;
    let whitespace_diff = repo.diff_with_options(&DiffOptions::new().ignore_whitespace())?;

    println!("   Normal diff shows {} files changed", normal_diff.len());
    println!(
        "   Whitespace-ignoring diff shows {} files changed",
        whitespace_diff.len()
    );
    println!();

    // Test 10: Show diff with HEAD
    println!("10. Diff with HEAD (all changes since last commit):");
    let head_diff = repo.diff_head()?;
    println!("    All changes since last commit:");
    for file in head_diff.iter() {
        println!("    - {} ({})", file.path.display(), file.status);
    }
    println!("    {}", head_diff.stats);
    println!();

    // Test 11: Different diff output formats
    println!("11. Testing different output formats:");

    let stat_diff = repo.diff_with_options(&DiffOptions::new().stat_only())?;
    println!("    Stat format:");
    println!("    {}", stat_diff);

    let numstat_diff = repo.diff_with_options(&DiffOptions::new().numstat())?;
    println!("    Numstat format - {} files changed", numstat_diff.len());
    for file in numstat_diff.iter() {
        println!(
            "    {} +{} -{}",
            file.path.display(),
            file.additions,
            file.deletions
        );
    }
    println!();

    // Test 12: Filtering by file status
    println!("12. Filtering files by status:");
    let all_changes = repo.diff_head()?;

    let added_files: Vec<_> = all_changes.files_with_status(DiffStatus::Added).collect();
    let modified_files: Vec<_> = all_changes
        .files_with_status(DiffStatus::Modified)
        .collect();
    let deleted_files: Vec<_> = all_changes.files_with_status(DiffStatus::Deleted).collect();

    println!("    Added files: {}", added_files.len());
    for file in added_files {
        println!("      - {}", file.path.display());
    }

    println!("    Modified files: {}", modified_files.len());
    for file in modified_files {
        println!("      - {}", file.path.display());
    }

    println!("    Deleted files: {}", deleted_files.len());
    for file in deleted_files {
        println!("      - {}", file.path.display());
    }
    println!();

    println!("=== Diff Operations Demo Complete ===");
    println!("All diff operations completed successfully!");
    println!("Summary of tested features:");
    println!("✓ Basic diff operations (working dir vs index)");
    println!("✓ Staged diff operations (index vs HEAD)");
    println!("✓ Diff between specific commits");
    println!("✓ Diff with various options (name-only, stat, numstat)");
    println!("✓ Path filtering");
    println!("✓ Whitespace handling options");
    println!("✓ File status filtering");
    println!("✓ Comprehensive diff statistics");

    println!("\nCleaning up temporary repository...");
    fs::remove_dir_all(&repo_path).ok();

    Ok(())
}

examples/tag_operations.rs (line 31)

fn main() -> Result<()> {
    println!("Rustic Git - Tag Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_tag_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Tag Demo User", "tags@example.com")?;

    // Create some commits to tag
    println!("\nCreating initial commits...");

    // First commit
    fs::write(
        repo_path.join("README.md"),
        "# Tag Demo Project\n\nDemonstrating Git tag operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let first_commit_hash = repo.commit("Initial commit: Add README")?;
    println!("Created commit: {}", first_commit_hash.short());

    // Second commit
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, tags!\");\n}\n",
    )?;
    repo.add(&["src/main.rs"])?;
    let second_commit_hash = repo.commit("Add main.rs with hello world")?;
    println!("Created commit: {}", second_commit_hash.short());

    // Third commit
    fs::write(
        repo_path.join("src/lib.rs"),
        "//! Tag demo library\n\npub fn greet(name: &str) -> String {\n    format!(\"Hello, {}!\", name)\n}\n",
    )?;
    repo.add(&["src/lib.rs"])?;
    let third_commit_hash = repo.commit("Add library with greet function")?;
    println!("Created commit: {}", third_commit_hash.short());

    // Demonstrate tag creation
    println!("\n=== Creating Tags ===");

    // Create lightweight tags
    println!("\n1. Creating lightweight tags:");

    let v0_1_0 = repo.create_tag("v0.1.0", Some(&first_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_1_0.name,
        v0_1_0.hash.short(),
        v0_1_0.tag_type
    );

    let v0_2_0 = repo.create_tag("v0.2.0", Some(&second_commit_hash))?;
    println!(
        "Created lightweight tag: {} -> {} ({})",
        v0_2_0.name,
        v0_2_0.hash.short(),
        v0_2_0.tag_type
    );

    // Create annotated tags
    println!("\n2. Creating annotated tags:");

    let options =
        TagOptions::new().with_message("First stable release with basic functionality".to_string());
    let v1_0_0 = repo.create_tag_with_options("v1.0.0", Some(&third_commit_hash), options)?;
    println!(
        "Created annotated tag: {} -> {} ({})",
        v1_0_0.name,
        v1_0_0.hash.short(),
        v1_0_0.tag_type
    );
    if let Some(message) = &v1_0_0.message {
        println!("  Message: {}", message);
    }

    // Tag current HEAD
    let latest_options = TagOptions::new().with_message("Latest development version".to_string());
    let latest_tag = repo.create_tag_with_options("latest", None, latest_options)?;
    println!(
        "Created annotated tag on HEAD: {} -> {} ({})",
        latest_tag.name,
        latest_tag.hash.short(),
        latest_tag.tag_type
    );

    // Create some feature tags
    println!("\n3. Creating feature and release candidate tags:");

    let feature_options = TagOptions::new().with_message("Feature branch snapshot".to_string());
    repo.create_tag_with_options("feature/demo", None, feature_options)?;

    let rc_options = TagOptions::new().with_message("Release candidate for v1.1.0".to_string());
    repo.create_tag_with_options("v1.1.0-rc1", None, rc_options)?;

    // Create a couple more version tags
    repo.create_tag("v0.3.0", None)?;
    repo.create_tag("v0.9.0", None)?;

    // Demonstrate tag listing and filtering
    println!("\n=== Tag Listing and Filtering ===");

    let tags = repo.tags()?;
    println!("\nAll tags ({} total):", tags.len());
    for tag in tags.iter() {
        let type_marker = match tag.tag_type {
            TagType::Lightweight => "L",
            TagType::Annotated => "A",
        };
        println!("  [{}] {} -> {}", type_marker, tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("      Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Filter by type
    println!("\nLightweight tags ({} total):", tags.lightweight_count());
    for tag in tags.lightweight() {
        println!("  {} -> {}", tag.name, tag.hash.short());
    }

    println!("\nAnnotated tags ({} total):", tags.annotated_count());
    for tag in tags.annotated() {
        println!("  {} -> {}", tag.name, tag.hash.short());
        if let Some(message) = &tag.message {
            println!("    Message: {}", message.lines().next().unwrap_or(""));
        }
    }

    // Search and filtering
    println!("\n=== Tag Searching ===");

    // Find specific tag
    if let Some(tag) = tags.find("v1.0.0") {
        println!("\nFound tag 'v1.0.0':");
        println!("  Type: {}", tag.tag_type);
        println!("  Hash: {}", tag.hash.short());
        if let Some(message) = &tag.message {
            println!("  Message: {}", message);
        }
    }

    // Find version tags
    let version_tags: Vec<_> = tags.find_containing("v").collect();
    println!(
        "\nVersion tags (containing 'v'): {} found",
        version_tags.len()
    );
    for tag in &version_tags {
        println!("  {}", tag.name);
    }

    // Find release candidates
    let rc_tags: Vec<_> = tags.find_containing("rc").collect();
    println!("\nRelease candidate tags: {} found", rc_tags.len());
    for tag in &rc_tags {
        println!("  {}", tag.name);
    }

    // Find tags for specific commit
    let tags_for_third_commit: Vec<_> = tags.for_commit(&third_commit_hash).collect();
    println!(
        "\nTags pointing to commit {}: {} found",
        third_commit_hash.short(),
        tags_for_third_commit.len()
    );
    for tag in &tags_for_third_commit {
        println!("  {}", tag.name);
    }

    // Demonstrate tag details
    println!("\n=== Tag Details ===");

    let detailed_tag = repo.show_tag("v1.0.0")?;
    println!("\nDetailed information for 'v1.0.0':");
    println!("  Name: {}", detailed_tag.name);
    println!("  Type: {}", detailed_tag.tag_type);
    println!("  Commit: {}", detailed_tag.hash);
    println!("  Short hash: {}", detailed_tag.hash.short());

    if let Some(message) = &detailed_tag.message {
        println!("  Message: {}", message);
    }

    if let Some(tagger) = &detailed_tag.tagger {
        println!("  Tagger: {}", tagger);
        println!(
            "  Tagged at: {}",
            tagger.timestamp.format("%Y-%m-%d %H:%M:%S UTC")
        );
    }

    if let Some(timestamp) = &detailed_tag.timestamp {
        println!("  Timestamp: {}", timestamp.format("%Y-%m-%d %H:%M:%S UTC"));
    }

    // Demonstrate tag operations
    println!("\n=== Tag Operations ===");

    // Create and force overwrite a tag
    println!("\n1. Testing tag overwrite:");

    // This should fail (tag already exists)
    match repo.create_tag("latest", None) {
        Ok(_) => println!("  ERROR: Should have failed to create existing tag"),
        Err(e) => println!("  Expected error creating existing tag: {}", e),
    }

    // Force overwrite
    let force_options = TagOptions::new()
        .with_force()
        .with_message("Forcefully updated latest tag".to_string());

    match repo.create_tag_with_options("latest", None, force_options) {
        Ok(tag) => println!("  Successfully force-created tag: {}", tag.name),
        Err(e) => println!("  Error force-creating tag: {}", e),
    }

    // Tag deletion
    println!("\n2. Testing tag deletion:");

    // Create a temporary tag to delete
    repo.create_tag("temp-tag", None)?;
    println!("  Created temporary tag: temp-tag");

    // Verify it exists
    let tags_before = repo.tags()?;
    let temp_exists_before = tags_before.find("temp-tag").is_some();
    println!("  Temp tag exists before deletion: {}", temp_exists_before);

    // Delete it
    repo.delete_tag("temp-tag")?;
    println!("  Deleted temp-tag");

    // Verify it's gone
    let tags_after = repo.tags()?;
    let temp_exists_after = tags_after.find("temp-tag").is_some();
    println!("  Temp tag exists after deletion: {}", temp_exists_after);

    // Summary
    println!("\n=== Summary ===");
    let final_tags = repo.tags()?;
    println!("\nFinal repository state:");
    println!("  Total tags: {}", final_tags.len());
    println!("  Lightweight tags: {}", final_tags.lightweight_count());
    println!("  Annotated tags: {}", final_tags.annotated_count());

    println!("\nTag creation options demonstrated:");
    println!("  ✓ Lightweight tags (simple references)");
    println!("  ✓ Annotated tags (with messages and metadata)");
    println!("  ✓ Tags on specific commits");
    println!("  ✓ Tags on current HEAD");
    println!("  ✓ Force tag creation/overwrite");

    println!("\nTag listing and filtering demonstrated:");
    println!("  ✓ List all tags");
    println!("  ✓ Filter by tag type (lightweight/annotated)");
    println!("  ✓ Search by name patterns");
    println!("  ✓ Find tags by commit hash");
    println!("  ✓ Show detailed tag information");

    println!("\nTag management demonstrated:");
    println!("  ✓ Tag creation with options");
    println!("  ✓ Tag deletion");
    println!("  ✓ Error handling for duplicate tags");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Tag operations example completed successfully!");

    Ok(())
}

examples/stash_operations.rs (line 32)

fn main() -> Result<()> {
    println!("Rustic Git - Stash Operations Example\n");

    // Use a temporary directory for this example
    let repo_path = env::temp_dir().join("rustic_git_stash_example");

    // Clean up any previous run
    if repo_path.exists() {
        fs::remove_dir_all(&repo_path).expect("Failed to clean up previous example");
    }

    println!("Initializing repository at: {}", repo_path.display());

    // Initialize repository and configure user
    let repo = Repository::init(&repo_path, false)?;
    repo.config()
        .set_user("Stash Demo User", "stash@example.com")?;

    // Create initial commit to have a base
    println!("\nCreating initial commit...");
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n",
    )?;
    repo.add(&["README.md"])?;
    let initial_commit = repo.commit("Initial commit: Add README")?;
    println!("Created initial commit: {}", initial_commit.short());

    // Create some work to stash
    println!("\n=== Creating Work to Stash ===");

    // Create tracked file modifications
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nAdded some new content!\n",
    )?;

    // Create new tracked files
    fs::create_dir_all(repo_path.join("src"))?;
    fs::write(
        repo_path.join("src/main.rs"),
        "fn main() {\n    println!(\"Hello, stash!\");\n}\n",
    )?;

    // Create untracked files
    fs::write(
        repo_path.join("untracked.txt"),
        "This file is not tracked by git\n",
    )?;
    fs::write(repo_path.join("temp.log"), "Temporary log file\n")?;

    // Stage some changes
    repo.add(&["src/main.rs"])?;

    println!("Created various types of changes:");
    println!("  - Modified tracked file (README.md)");
    println!("  - Added new file and staged it (src/main.rs)");
    println!("  - Created untracked files (untracked.txt, temp.log)");

    // Check repository status before stashing
    let status = repo.status()?;
    println!("\nRepository status before stashing:");
    println!("  Staged files: {}", status.staged_files().count());
    println!("  Unstaged files: {}", status.unstaged_files().count());
    println!("  Untracked files: {}", status.untracked_entries().count());

    // Demonstrate stash creation
    println!("\n=== Creating Stashes ===");

    // 1. Simple stash save
    println!("\n1. Creating simple stash:");
    let simple_stash = repo.stash_save("WIP: working on main function")?;
    println!("Created stash: {}", simple_stash);
    println!("  Index: {}", simple_stash.index);
    println!("  Branch: {}", simple_stash.branch);
    println!("  Hash: {}", simple_stash.hash.short());

    // Check status after stash
    let status_after_stash = repo.status()?;
    println!("\nStatus after simple stash:");
    println!(
        "  Staged files: {}",
        status_after_stash.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_stash.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_stash.untracked_entries().count()
    );

    // 2. Make more changes and create stash with untracked files
    println!("\n2. Creating stash with untracked files:");

    // Modify file again
    fs::write(
        repo_path.join("README.md"),
        "# Stash Demo Project\n\nDemonstrating Git stash operations.\n\nSecond round of changes!\n",
    )?;

    // Create more untracked files
    fs::write(repo_path.join("config.json"), "{\"debug\": true}\n")?;

    let untracked_options = StashOptions::new().with_untracked().with_keep_index();
    let untracked_stash = repo.stash_push(
        "WIP: config changes with untracked files",
        untracked_options,
    )?;
    println!("Created stash with untracked files: {}", untracked_stash);

    // 3. Create stash with specific paths
    println!("\n3. Creating stash with specific paths:");

    // Make changes to multiple files and add them to git
    fs::write(repo_path.join("file1.txt"), "Content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Content for file 3\n")?;

    // Add all files so they're tracked
    repo.add(&["file1.txt", "file2.txt", "file3.txt"])?;

    // Now modify them so there are changes to stash
    fs::write(repo_path.join("file1.txt"), "Modified content for file 1\n")?;
    fs::write(repo_path.join("file2.txt"), "Modified content for file 2\n")?;
    fs::write(repo_path.join("file3.txt"), "Modified content for file 3\n")?;

    let path_options = StashOptions::new().with_paths(vec!["file1.txt".into(), "file2.txt".into()]);
    let path_stash = repo.stash_push("WIP: specific files only", path_options)?;
    println!("Created stash with specific paths: {}", path_stash);

    // Demonstrate stash listing and filtering
    println!("\n=== Stash Listing and Filtering ===");

    let stashes = repo.stash_list()?;
    println!("\nAll stashes ({} total):", stashes.len());
    for stash in stashes.iter() {
        println!(
            "  [{}] {} -> {}",
            stash.index,
            stash.message,
            stash.hash.short()
        );
        println!(
            "      Branch: {} | Created: {}",
            stash.branch,
            stash.timestamp.format("%Y-%m-%d %H:%M:%S")
        );
    }

    // Test filtering
    println!("\nFiltering examples:");

    // Find stashes containing specific text
    let wip_stashes: Vec<_> = stashes.find_containing("WIP").collect();
    println!("Stashes containing 'WIP': {} found", wip_stashes.len());
    for stash in &wip_stashes {
        println!("  - {}", stash.message);
    }

    let config_stashes: Vec<_> = stashes.find_containing("config").collect();
    println!(
        "Stashes containing 'config': {} found",
        config_stashes.len()
    );

    // Get latest stash
    if let Some(latest) = stashes.latest() {
        println!("Latest stash: {}", latest.message);
    }

    // Get specific stash by index
    if let Some(second_stash) = stashes.get(1) {
        println!("Second stash: {}", second_stash.message);
    }

    // Demonstrate stash content viewing
    println!("\n=== Viewing Stash Contents ===");

    println!("\nShowing contents of latest stash:");
    let stash_contents = repo.stash_show(0)?;
    println!("{}", stash_contents);

    // Demonstrate stash application
    println!("\n=== Applying and Popping Stashes ===");

    println!("\n1. Testing stash apply (keeps stash in list):");
    let stashes_before_apply = repo.stash_list()?;
    println!("Stashes before apply: {}", stashes_before_apply.len());

    // Apply the latest stash
    repo.stash_apply(0, StashApplyOptions::new())?;
    println!("Applied stash@{{0}}");

    let stashes_after_apply = repo.stash_list()?;
    println!("Stashes after apply: {}", stashes_after_apply.len());

    // Check what was restored
    let status_after_apply = repo.status()?;
    println!("Status after apply:");
    println!(
        "  Staged files: {}",
        status_after_apply.staged_files().count()
    );
    println!(
        "  Unstaged files: {}",
        status_after_apply.unstaged_files().count()
    );
    println!(
        "  Untracked files: {}",
        status_after_apply.untracked_entries().count()
    );

    println!("\n2. Testing stash pop (removes stash from list):");

    // First, stash current changes again to have something to pop
    repo.stash_save("Temporary stash for pop test")?;

    let stashes_before_pop = repo.stash_list()?;
    println!("Stashes before pop: {}", stashes_before_pop.len());

    // Pop the latest stash
    repo.stash_pop(0, StashApplyOptions::new().with_quiet())?;
    println!("Popped stash@{{0}}");

    let stashes_after_pop = repo.stash_list()?;
    println!("Stashes after pop: {}", stashes_after_pop.len());

    // Demonstrate advanced apply options
    println!("\n3. Testing apply with index restoration:");

    // Create a stash with staged changes
    fs::write(repo_path.join("staged_file.txt"), "This will be staged\n")?;
    repo.add(&["staged_file.txt"])?;

    fs::write(
        repo_path.join("unstaged_file.txt"),
        "This will be unstaged\n",
    )?;

    repo.stash_save("Stash with staged and unstaged changes")?;

    // Apply with index restoration
    let apply_options = StashApplyOptions::new().with_index();
    repo.stash_apply(0, apply_options)?;
    println!("Applied stash with index restoration");

    let final_status = repo.status()?;
    println!("Final status after index restoration:");
    println!("  Staged files: {}", final_status.staged_files().count());
    println!(
        "  Unstaged files: {}",
        final_status.unstaged_files().count()
    );

    // Demonstrate stash management
    println!("\n=== Stash Management ===");

    // Create a few test stashes
    for i in 1..=3 {
        fs::write(
            repo_path.join(format!("test{}.txt", i)),
            format!("Test content {}\n", i),
        )?;
        repo.stash_save(&format!("Test stash {}", i))?;
    }

    let management_stashes = repo.stash_list()?;
    println!(
        "\nCreated {} test stashes for management demo",
        management_stashes.len()
    );

    // Drop a specific stash
    println!("\n1. Dropping middle stash:");
    println!("Before drop: {} stashes", management_stashes.len());

    repo.stash_drop(1)?; // Drop second stash (index 1)
    println!("Dropped stash@{{1}}");

    let after_drop = repo.stash_list()?;
    println!("After drop: {} stashes", after_drop.len());

    // Show remaining stashes
    println!("Remaining stashes:");
    for stash in after_drop.iter() {
        println!("  [{}] {}", stash.index, stash.message);
    }

    // Clear all stashes
    println!("\n2. Clearing all stashes:");
    repo.stash_clear()?;
    println!("Cleared all stashes");

    let final_stashes = repo.stash_list()?;
    println!("Stashes after clear: {}", final_stashes.len());

    // Demonstrate error handling
    println!("\n=== Error Handling ===");

    println!("\n1. Testing operations on empty stash list:");

    // Try to apply non-existent stash
    match repo.stash_apply(0, StashApplyOptions::new()) {
        Ok(_) => println!("ERROR: Should have failed to apply non-existent stash"),
        Err(e) => println!("Expected error applying non-existent stash: {}", e),
    }

    // Try to show non-existent stash
    match repo.stash_show(0) {
        Ok(_) => println!("ERROR: Should have failed to show non-existent stash"),
        Err(e) => println!("Expected error showing non-existent stash: {}", e),
    }

    // Try to drop non-existent stash
    match repo.stash_drop(0) {
        Ok(_) => println!("ERROR: Should have failed to drop non-existent stash"),
        Err(e) => println!("Expected error dropping non-existent stash: {}", e),
    }

    // Summary
    println!("\n=== Summary ===");
    println!("\nStash operations demonstrated:");
    println!("  ✓ Basic stash save and push with options");
    println!("  ✓ Stash with untracked files and keep-index");
    println!("  ✓ Stash specific paths only");
    println!("  ✓ Comprehensive stash listing and filtering");
    println!("  ✓ Stash content viewing");
    println!("  ✓ Apply vs pop operations");
    println!("  ✓ Index restoration during apply");
    println!("  ✓ Stash dropping and clearing");
    println!("  ✓ Error handling for edge cases");

    println!("\nStash options demonstrated:");
    println!("  ✓ with_untracked() - Include untracked files");
    println!("  ✓ with_keep_index() - Keep staged changes");
    println!("  ✓ with_paths() - Stash specific files only");
    println!("  ✓ with_index() - Restore staged state on apply");
    println!("  ✓ with_quiet() - Suppress output messages");

    println!("\nStash filtering demonstrated:");
    println!("  ✓ find_containing() - Search by message content");
    println!("  ✓ latest() - Get most recent stash");
    println!("  ✓ get() - Get stash by index");
    println!("  ✓ for_branch() - Filter by branch name");

    // Clean up
    println!("\nCleaning up example repository...");
    fs::remove_dir_all(&repo_path)?;
    println!("Stash operations example completed successfully!");

    Ok(())
}

Additional examples can be found in:

• examples/file_lifecycle_operations.rs

Trait Implementations

impl Debug for Repository

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

Formats the value using the given formatter.