refactor: improve code organization and documentation quality

- Enhance error handling patterns across core modules
- Update examples with better documentation and clarity
- Refactor command modules for improved maintainability
- Standardize code formatting and structure
- Update project documentation and guidelines

Author: eugener

CLAUDE.md

@@ -21,7 +21,7 @@
 - Utility functions: git(args, working_dir) -> Result<String>, git_raw(args, working_dir) -> Result<Output>
 - Command modules: status.rs, add.rs, commit.rs (in src/commands/)
 - Core types: Hash (in src/types.rs)
-- Run `cargo build && cargo test && cargo clippy --all-targets --all-features -- -D warnings` after code changes
+- Run `cargo fmt && cargo build && cargo test && cargo clippy --all-targets --all-features -- -D warnings` after code changes
 - Make sure all examples are running
 
 ## Examples

examples/commit_workflows.rs

@@ -9,15 +9,15 @@
 //!
 //! Run with: cargo run --example commit_workflows
 
-use rustic_git::{Repository, Hash, Result};
+use rustic_git::{Hash, Repository, Result};
 use std::fs;
 use std::path::Path;
 
 fn main() -> Result<()> {
     println!("Rustic Git - Commit Workflows Example\n");
 
     let repo_path = "/tmp/rustic_git_commit_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");
@@ -33,65 +33,74 @@ fn main() -> Result<()> {
     // Create initial files
     println!("Creating initial project files...");
     fs::create_dir_all(format!("{}/src", repo_path))?;
-    
+
     fs::write(
         format!("{}/README.md", repo_path),
-        "# Commit Demo Project\n\nThis project demonstrates commit workflows with rustic-git.\n"
+        "# Commit Demo Project\n\nThis project demonstrates commit workflows with rustic-git.\n",
     )?;
-    
+
     fs::write(
         format!("{}/src/main.rs", repo_path),
         r#"fn main() {
     println!("Hello, Commit Demo!");
 }
-"#
+"#,
     )?;
-    
-    fs::write(format!("{}/Cargo.toml", repo_path), r#"[package]
+
+    fs::write(
+        format!("{}/Cargo.toml", repo_path),
+        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());
-    
+    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!();
@@ -101,8 +110,10 @@ edition = "2021"
     // Create more files to commit with custom author
     println!("Adding features for custom author commit...");
     fs::create_dir_all(format!("{}/tests", repo_path))?;
-    
-    fs::write(format!("{}/src/lib.rs", repo_path), r#"//! Commit demo library
+
+    fs::write(
+        format!("{}/src/lib.rs", repo_path),
+        r#"//! Commit demo library
 
 pub fn greet(name: &str) -> String {
     format!("Hello, {}! This is a commit demo.", name)
@@ -117,17 +128,21 @@ mod tests {
         assert_eq!(greet("Alice"), "Hello, Alice! This is a commit demo.");
     }
 }
-"#)?;
+"#,
+    )?;
 
-    fs::write(format!("{}/tests/integration_test.rs", repo_path), r#"use commit_demo::greet;
+    fs::write(
+        format!("{}/tests/integration_test.rs", repo_path),
+        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");
 
@@ -138,7 +153,7 @@ fn test_integration() {
         "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 <[email protected]>"
     )?;
-    
+
     println!("Commit with custom author created!");
     display_hash_info(&second_hash, "Second commit (custom author)");
     println!();
@@ -147,23 +162,28 @@ fn test_integration() {
 
     // 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(format!("{}/Cargo.toml", repo_path), r#"[package]
+    fs::write(
+        format!("{}/Cargo.toml", repo_path),
+        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(format!("{}/CHANGELOG.md", repo_path), r#"# Changelog
+    fs::write(
+        format!("{}/CHANGELOG.md", repo_path),
+        r#"# Changelog
 
 ## [0.2.0] - 2024-01-01
 
@@ -177,18 +197,21 @@ description = "A demo project for commit workflows"
 ### 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 <[email protected]>"
+        "Doc Writer <[email protected]>",
     )?;
     commit_hashes.push(fourth_hash);
-    
+
     // Commit 5: Final polish
     println!("Step 3: Final polish...");
-    fs::write(format!("{}/README.md", repo_path), r#"# Commit Demo Project
+    fs::write(
+        format!("{}/README.md", repo_path),
+        r#"# Commit Demo Project
 
 This project demonstrates commit workflows with rustic-git.
 
@@ -214,17 +237,18 @@ fn main() {
 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));
@@ -233,9 +257,12 @@ See CHANGELOG.md for version history.
 
     // Compare hashes
     println!("Hash comparisons:");
-    println!("   First commit == Last commit: {}", commit_hashes[0] == commit_hashes[4]);
+    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() {
@@ -260,17 +287,23 @@ See CHANGELOG.md for version history.
     match repo.commit_with_author("This should also fail", "Test Author <[email protected]>") {
         Ok(_hash) => println!("   Unexpectedly succeeded with empty custom author commit"),
         Err(e) => {
-            println!("   Expected error for empty commit with custom author: {:?}", 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(format!("{}/temp_for_empty_message.txt", repo_path), "temp content")?;
+    fs::write(
+        format!("{}/temp_for_empty_message.txt", repo_path),
+        "temp content",
+    )?;
     repo.add(&["temp_for_empty_message.txt"])?;
-    
+
     match repo.commit("") {
         Ok(hash) => {
             println!("   Commit with empty message succeeded: {}", hash.short());
@@ -289,7 +322,10 @@ See CHANGELOG.md for version history.
     if final_status.is_clean() {
         println!("Repository is clean - all changes committed!");
     } else {
-        println!("Repository has {} uncommitted changes", final_status.files.len());
+        println!(
+            "Repository has {} uncommitted changes",
+            final_status.files.len()
+        );
     }
 
     println!("\nWorkflow summary:");
@@ -312,11 +348,15 @@ fn display_hash_info(hash: &Hash, context: &str) {
     println!("      Full hash: {}", hash);
     println!("      Short hash: {}", hash.short());
     println!("      Hash length: {} chars", hash.as_str().len());
-    
+
     // Show first and last few characters for visual reference
     let full = hash.as_str();
     if full.len() >= 10 {
-        println!("      Pattern: {}...{}", &full[..5], &full[full.len()-5..]);
+        println!(
+            "      Pattern: {}...{}",
+            &full[..5],
+            &full[full.len() - 5..]
+        );
     }
 }
 
@@ -329,4 +369,4 @@ fn all_unique(hashes: &[Hash]) -> bool {
         }
     }
     true
-}
+}