Merge branch 'master' into eugener-patch-1

Author: eugener

.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(cargo:*)"
+      "Bash(cargo:*)",
+      "Bash(sed:*)"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -1,6 +1,7 @@
 - We are using Rust edition of 2024
 - Follow the Rust style guide for naming conventions and formatting
 - Implement best practices for code organization and maintainability
+- Do not use emoji while coding
 
 ## Design Choices
 - **Repository-centric API**: Static lifecycle methods (init, open) return Repository instances, instance methods for git operations
@@ -21,3 +22,17 @@
 - Command modules: status.rs, add.rs, commit.rs (in src/commands/)
 - Core types: Hash (in src/types.rs)
 - Run `cargo build && cargo test` after code changes
+- Make sure all examples are running
+
+## Examples
+The `examples/` directory contains comprehensive demonstrations of library functionality:
+
+- **basic_usage.rs**: Complete workflow from init to commit - demonstrates fundamental rustic-git usage
+- **repository_operations.rs**: Repository lifecycle - init regular/bare repos, open existing repos, error handling
+- **status_checking.rs**: GitStatus and FileStatus usage - all status query methods and file state filtering
+- **staging_operations.rs**: Staging operations - add(), add_all(), add_update() with before/after comparisons
+- **commit_workflows.rs**: Commit operations and Hash type - commit(), commit_with_author(), Hash methods
+- **error_handling.rs**: Comprehensive error handling patterns - GitError variants, recovery strategies
+
+Run examples with: `cargo run --example <example_name>`
+All examples use temporary directories and include cleanup for safe execution.

README.md

@@ -260,6 +260,43 @@ fn main() -> rustic_git::Result<()> {
 }
 ```
 
+## Examples
+
+The `examples/` directory contains comprehensive demonstrations of library functionality:
+
+### Running Examples
+
+```bash
+# Complete workflow from init to commit
+cargo run --example basic_usage
+
+# Repository lifecycle operations
+cargo run --example repository_operations
+
+# Status checking and file state filtering  
+cargo run --example status_checking
+
+# Staging operations (add, add_all, add_update)
+cargo run --example staging_operations
+
+# Commit workflows and Hash type usage
+cargo run --example commit_workflows
+
+# Error handling patterns and recovery strategies
+cargo run --example error_handling
+```
+
+### Example Files
+
+- **`basic_usage.rs`** - Demonstrates the fundamental rustic-git workflow: initialize a repository, create files, check status, stage changes, and create commits
+- **`repository_operations.rs`** - Shows repository lifecycle operations including initializing regular and bare repositories, opening existing repos, and handling errors
+- **`status_checking.rs`** - Comprehensive demonstration of GitStatus and FileStatus usage with all query methods and filtering capabilities
+- **`staging_operations.rs`** - Shows all staging methods (add, add_all, add_update) with before/after status comparisons
+- **`commit_workflows.rs`** - Demonstrates commit operations and Hash type methods, including custom authors and hash management
+- **`error_handling.rs`** - Comprehensive error handling patterns showing GitError variants, recovery strategies, and best practices
+
+All examples use temporary directories in `/tmp/` and include automatic cleanup for safe execution.
+
 ## Testing
 
 Run the test suite:

examples/basic_usage.rs

@@ -0,0 +1,127 @@
+//! Basic Usage Example
+//!
+//! This example demonstrates the fundamental workflow of the rustic-git library:
+//! - Initialize a new repository
+//! - Create some files
+//! - Check repository status
+//! - Stage files
+//! - Create a commit
+//!
+//! Run with: cargo run --example basic_usage
+
+use rustic_git::{Repository, Result};
+use std::fs;
+use std::path::Path;
+
+fn main() -> Result<()> {
+    println!("Rustic Git - Basic Usage Example\n");
+
+    // Use a temporary directory for this example
+    let repo_path = "/tmp/rustic_git_basic_example";
+
+    // Clean up any previous run
+    if Path::new(repo_path).exists() {
+        fs::remove_dir_all(repo_path).expect("Failed to clean up previous example");
+    }
+
+    println!("Initializing new repository at: {}", repo_path);
+
+    // 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(format!("{}/src", repo_path))?;
+
+    fs::write(
+        format!("{}/README.md", repo_path),
+        "# My Awesome Project\n\nThis is a demo project for rustic-git!\n",
+    )?;
+
+    fs::write(
+        format!("{}/src/main.rs", repo_path),
+        r#"fn main() {
+    println!("Hello from rustic-git example!");
+}
+"#,
+    )?;
+
+    fs::write(
+        format!("{}/src/lib.rs", repo_path),
+        "// 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!("   Modified files: {}", status.modified_files().len());
+        println!("   Untracked files: {}", status.untracked_files().len());
+
+        // Show untracked files
+        for filename in status.untracked_files() {
+            println!("      - {}", filename);
+        }
+    }
+    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.files.len()
+        );
+        for (file_status, filename) in &status_after_staging.files {
+            println!("      {:?}: {}", file_status, filename);
+        }
+    }
+    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(())
+}