feat: implement enhanced status API with staged/unstaged tracking

- Replace simple FileStatus enum with IndexStatus and WorktreeStatus enums
- Add FileEntry struct combining PathBuf with both status types
- Implement Box<[FileEntry]> for immutable, memory-efficient storage
- Add const from_char/to_char methods with zero runtime cost
- Provide iterator-based API methods: staged_files(), unstaged_files(), untracked_entries()
- Add status filtering by IndexStatus and WorktreeStatus
- Update all examples and documentation to showcase new capabilities
- Maintain Git-accurate representation of index vs worktree states

Author: eugener

CLAUDE.md

@@ -19,13 +19,18 @@
 
 ## Implementation
 - Available methods: Repository::init(path, bare), Repository::open(path), Repository::status(), Repository::add(paths), Repository::add_all(), Repository::add_update(), Repository::commit(message), Repository::commit_with_author(message, author)
-- Status functionality: GitStatus with FileStatus enum, files as Box<[(FileStatus, String)]>
+- **Status functionality**: Enhanced GitStatus API with separate staged/unstaged file tracking
+  - GitStatus with entries as Box<[FileEntry]> for immutable, efficient storage
+  - FileEntry contains PathBuf, IndexStatus, and WorktreeStatus for precise Git state representation
+  - IndexStatus enum: Clean, Modified, Added, Deleted, Renamed, Copied (with const from_char/to_char methods)
+  - WorktreeStatus enum: Clean, Modified, Deleted, Untracked, Ignored (with const from_char/to_char methods)
+  - API methods: staged_files(), unstaged_files(), untracked_entries(), files_with_index_status(), files_with_worktree_status()
 - Add functionality: Stage specific files, all changes, or tracked file updates
 - Commit functionality: Create commits and return Hash of created commit
 - Hash type: Universal git object hash representation with short() and Display methods
 - 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)
+- Core types: Hash (in src/types.rs), IndexStatus, WorktreeStatus, FileEntry (in src/commands/status.rs)
 - Run `cargo fmt && cargo build && cargo test && cargo clippy --all-targets --all-features -- -D warnings` after code changes
 - Make sure all examples are running
 
@@ -34,7 +39,7 @@ The `examples/` directory contains comprehensive demonstrations of library funct
 
 - **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
+- **status_checking.rs**: Enhanced GitStatus API usage - staged/unstaged file queries, IndexStatus/WorktreeStatus filtering, comprehensive status analysis
 - **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

README.md

@@ -9,12 +9,15 @@ Rustic Git provides a simple, ergonomic interface for common Git operations. It
 ## Features
 
 - ✅ Repository initialization and opening
-- ✅ File status checking with detailed parsing
-- ✅ File staging (add files, add all, add updates)
+- ✅ **Enhanced file status checking** with separate staged/unstaged tracking
+- ✅ **Precise Git state representation** using IndexStatus and WorktreeStatus enums
+- ✅ File staging (add files, add all, add updates) 
 - ✅ Commit creation with hash return
-- ✅ Type-safe error handling
+- ✅ Type-safe error handling with custom GitError enum
 - ✅ Universal `Hash` type for Git objects
-- ✅ Comprehensive test coverage
+- ✅ **Immutable collections** (Box<[FileEntry]>) for memory efficiency
+- ✅ **Const enum conversions** with zero runtime cost
+- ✅ Comprehensive test coverage (80+ tests)
 
 ## Installation
 
@@ -28,7 +31,7 @@ rustic-git = "0.1.0"
 ## Quick Start
 
 ```rust
-use rustic_git::{Repository, Result};
+use rustic_git::{Repository, Result, IndexStatus, WorktreeStatus};
 
 fn main() -> Result<()> {
     // Initialize a new repository
@@ -37,11 +40,24 @@ fn main() -> Result<()> {
     // Or open an existing repository
     let repo = Repository::open("/path/to/existing/repo")?;
 
-    // Check repository status
+    // Check repository status with enhanced API
     let status = repo.status()?;
     if !status.is_clean() {
-        println!("Modified files: {:?}", status.modified_files());
-        println!("Untracked files: {:?}", status.untracked_files());
+        // Get files by staging state
+        let staged_count = status.staged_files().count();
+        let unstaged_count = status.unstaged_files().count();
+        let untracked_count = status.untracked_entries().count();
+        
+        println!("Repository status:");
+        println!("  Staged: {} files", staged_count);
+        println!("  Unstaged: {} files", unstaged_count);
+        println!("  Untracked: {} files", untracked_count);
+
+        // Filter by specific status types
+        let modified_files: Vec<_> = status
+            .files_with_worktree_status(WorktreeStatus::Modified)
+            .collect();
+        println!("  Modified files: {:?}", modified_files);
     }
 
     // Stage files
@@ -85,7 +101,7 @@ let repo = Repository::open("/path/to/existing/repo")?;
 
 #### `Repository::status() -> Result<GitStatus>`
 
-Get the current repository status.
+Get the current repository status with enhanced staged/unstaged file tracking.
 
 ```rust
 let status = repo.status()?;
@@ -97,36 +113,81 @@ if status.is_clean() {
     println!("Repository has changes");
 }
 
-// Get files by status
-let modified = status.modified_files();
-let untracked = status.untracked_files();
-
-// Or work with all files directly
-for (file_status, filename) in &status.files {
-    println!("{:?}: {}", file_status, filename);
+// Get files by staging state
+let staged_files: Vec<_> = status.staged_files().collect();
+let unstaged_files: Vec<_> = status.unstaged_files().collect();
+let untracked_files: Vec<_> = status.untracked_entries().collect();
+
+// Filter by specific status types
+let modified_in_index: Vec<_> = status
+    .files_with_index_status(IndexStatus::Modified)
+    .collect();
+let modified_in_worktree: Vec<_> = status
+    .files_with_worktree_status(WorktreeStatus::Modified)
+    .collect();
+
+// Work with all file entries directly
+for entry in status.entries() {
+    println!("[{}][{}] {}", 
+        entry.index_status.to_char(), 
+        entry.worktree_status.to_char(),
+        entry.path.display()
+    );
 }
 ```
 
 The `GitStatus` struct contains:
-- `files: Box<[(FileStatus, String)]>` - All files with their status
+- `entries: Box<[FileEntry]>` - Immutable collection of file entries
 - `is_clean()` - Returns true if no changes
 - `has_changes()` - Returns true if any changes exist
-- `modified_files()` - Get all modified files
-- `untracked_files()` - Get all untracked files
-- `files_with_status(status)` - Get files with specific status
+- `staged_files()` - Iterator over files with index changes (staged)
+- `unstaged_files()` - Iterator over files with worktree changes (unstaged)
+- `untracked_entries()` - Iterator over untracked files
+- `ignored_files()` - Iterator over ignored files
+- `files_with_index_status(status)` - Filter by specific index status
+- `files_with_worktree_status(status)` - Filter by specific worktree status
 
 #### File Status Types
 
+The enhanced status API uses separate enums for index (staged) and worktree (unstaged) states:
+
 ```rust
-pub enum FileStatus {
-    Modified,   // File has been modified
-    Added,      // File has been added to index
-    Deleted,    // File has been deleted
-    Renamed,    // File has been renamed
-    Copied,     // File has been copied
-    Untracked,  // File is not tracked by git
-    Ignored,    // File is ignored by git
+// Index (staging area) status
+pub enum IndexStatus {
+    Clean,      // No changes in index
+    Modified,   // File modified in index
+    Added,      // File added to index
+    Deleted,    // File deleted in index
+    Renamed,    // File renamed in index
+    Copied,     // File copied in index
+}
+
+// Worktree (working directory) status
+pub enum WorktreeStatus {
+    Clean,      // No changes in worktree
+    Modified,   // File modified in worktree
+    Deleted,    // File deleted in worktree
+    Untracked,  // File not tracked by git
+    Ignored,    // File ignored by git
 }
+
+// File entry combining both states
+pub struct FileEntry {
+    pub path: PathBuf,
+    pub index_status: IndexStatus,
+    pub worktree_status: WorktreeStatus,
+}
+```
+
+Both enums support const character conversion:
+```rust
+// Convert to/from git porcelain characters
+let status = IndexStatus::from_char('M');  // IndexStatus::Modified
+let char = status.to_char();               // 'M'
+
+// Display formatting
+println!("{}", IndexStatus::Modified);     // Prints: M
+println!("{}", WorktreeStatus::Untracked); // Prints: ?
 ```
 
 ### Staging Operations
@@ -220,7 +281,7 @@ match repo.commit("message") {
 ## Complete Workflow Example
 
 ```rust
-use rustic_git::{Repository, FileStatus};
+use rustic_git::{Repository, IndexStatus, WorktreeStatus};
 use std::fs;
 
 fn main() -> rustic_git::Result<()> {
@@ -229,23 +290,36 @@ fn main() -> rustic_git::Result<()> {
 
     // Create some files
     fs::write("./my-project/README.md", "# My Project")?;
-    fs::write("./my-project/src/main.rs", "fn main() { println!(\"Hello!\"); }")?;
     fs::create_dir_all("./my-project/src")?;
+    fs::write("./my-project/src/main.rs", "fn main() { println!(\"Hello!\"); }")?;
 
-    // Check status
+    // Check status with enhanced API
     let status = repo.status()?;
-    println!("Found {} untracked files", status.untracked_files().len());
+    let untracked_count = status.untracked_entries().count();
+    println!("Found {} untracked files", untracked_count);
+    
+    // Display detailed status
+    for entry in status.entries() {
+        println!("[{}][{}] {}", 
+            entry.index_status.to_char(),
+            entry.worktree_status.to_char(),
+            entry.path.display()
+        );
+    }
 
     // Stage all files
     repo.add_all()?;
 
-    // Verify staging
+    // Verify staging with enhanced API
     let status = repo.status()?;
-    let added_files: Vec<_> = status.files.iter()
-        .filter(|(s, _)| matches!(s, FileStatus::Added))
-        .map(|(_, f)| f)
+    let staged_files: Vec<_> = status.staged_files().collect();
+    println!("Staged {} files", staged_files.len());
+    
+    // Show specifically added files
+    let added_files: Vec<_> = status
+        .files_with_index_status(IndexStatus::Added)
         .collect();
-    println!("Staged files: {:?}", added_files);
+    println!("Added files: {:?}", added_files);
 
     // Create initial commit
     let hash = repo.commit("Initial commit with project structure")?;
@@ -273,7 +347,7 @@ cargo run --example basic_usage
 # Repository lifecycle operations
 cargo run --example repository_operations
 
-# Status checking and file state filtering
+# Enhanced status API with staged/unstaged tracking
 cargo run --example status_checking
 
 # Staging operations (add, add_all, add_update)

examples/basic_usage.rs

@@ -62,12 +62,12 @@ fn main() -> Result<()> {
         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());
+        println!("   Unstaged files: {}", status.unstaged_files().count());
+        println!("   Untracked files: {}", status.untracked_entries().count());
 
         // Show untracked files
-        for filename in status.untracked_files() {
-            println!("      - {}", filename);
+        for entry in status.untracked_entries() {
+            println!("      - {}", entry.path.display());
         }
     }
     println!();
@@ -91,10 +91,15 @@ fn main() -> Result<()> {
     } else {
         println!(
             "   Files staged for commit: {}",
-            status_after_staging.files.len()
+            status_after_staging.entries.len()
         );
-        for (file_status, filename) in &status_after_staging.files {
-            println!("      {:?}: {}", file_status, filename);
+        for entry in &status_after_staging.entries {
+            println!(
+                "      Index {:?}, Worktree {:?}: {}",
+                entry.index_status,
+                entry.worktree_status,
+                entry.path.display()
+            );
         }
     }
     println!();

examples/commit_workflows.rs

@@ -324,7 +324,7 @@ See CHANGELOG.md for version history.
     } else {
         println!(
             "Repository has {} uncommitted changes",
-            final_status.files.len()
+            final_status.entries.len()
         );
     }
 

examples/error_handling.rs

@@ -131,7 +131,7 @@ fn demonstrate_file_operation_errors(repo_path: &str) -> Result<()> {
             println!("   Partially succeeded - some Git versions allow this");
             // Check what actually got staged
             let status = repo.status()?;
-            println!("   {} files staged despite error", status.files.len());
+            println!("   {} files staged despite error", status.entries.len());
         }
         Err(GitError::CommandFailed(msg)) => {
             println!("   CommandFailed caught: {}", msg);
@@ -228,7 +228,7 @@ fn demonstrate_error_recovery_patterns(repo_path: &str) -> Result<()> {
                     let status = repo.status()?;
                     println!(
                         "      add_all() succeeded, {} files staged",
-                        status.files.len()
+                        status.entries.len()
                     );
                 }
                 Err(fallback_error) => {
@@ -290,11 +290,16 @@ fn demonstrate_error_recovery_patterns(repo_path: &str) -> Result<()> {
     if status.is_clean() {
         println!("      Repository is clean - no commit needed");
     } else {
-        println!("      Repository has {} changes", status.files.len());
+        println!("      Repository has {} changes", status.entries.len());
 
         // Show what would be committed
-        for (file_status, filename) in &status.files {
-            println!("         {:?}: {}", file_status, filename);
+        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

examples/repository_operations.rs

@@ -66,7 +66,7 @@ fn main() -> Result<()> {
 
             // Test that we can perform operations on the opened repo
             let status = opened_repo.status()?;
-            println!("   Repository status: {} files", status.files.len());
+            println!("   Repository status: {} files", status.entries.len());
         }
         Err(e) => {
             println!("Failed to open regular repository: {:?}", e);
@@ -83,7 +83,7 @@ fn main() -> Result<()> {
 
             // Note: status operations might behave differently on bare repos
             match opened_bare.status() {
-                Ok(status) => println!("   Bare repository status: {} files", status.files.len()),
+                Ok(status) => println!("   Bare repository status: {} files", status.entries.len()),
                 Err(e) => println!(
                     "   Note: Status check on bare repo failed (expected): {:?}",
                     e