feat(stash): add comprehensive stash management API

Add complete stash operations implementation including save, apply, pop,
list, show, drop, and clear functionality with advanced options support.
Includes type-safe filtering, builder patterns, and comprehensive example.

Author: eugener

CLAUDE.md

@@ -56,7 +56,7 @@
   - Author struct: name, email, timestamp with Display implementation
   - CommitMessage: subject and optional body parsing
   - CommitDetails: full commit info including file changes and diff stats
-- **Core types**: Hash (in src/types.rs), IndexStatus, WorktreeStatus, FileEntry (in src/commands/status.rs), Branch, BranchList, BranchType (in src/commands/branch.rs), Commit, CommitLog, Author, CommitMessage, CommitDetails, LogOptions (in src/commands/log.rs), RepoConfig (in src/commands/config.rs), Remote, RemoteList, FetchOptions, PushOptions (in src/commands/remote.rs), RestoreOptions, RemoveOptions, MoveOptions (in src/commands/files.rs), DiffOutput, FileDiff, DiffStatus, DiffOptions, DiffStats, DiffChunk, DiffLine, DiffLineType (in src/commands/diff.rs), Tag, TagList, TagType, TagOptions (in src/commands/tag.rs)
+- **Core types**: Hash (in src/types.rs), IndexStatus, WorktreeStatus, FileEntry (in src/commands/status.rs), Branch, BranchList, BranchType (in src/commands/branch.rs), Commit, CommitLog, Author, CommitMessage, CommitDetails, LogOptions (in src/commands/log.rs), RepoConfig (in src/commands/config.rs), Remote, RemoteList, FetchOptions, PushOptions (in src/commands/remote.rs), RestoreOptions, RemoveOptions, MoveOptions (in src/commands/files.rs), DiffOutput, FileDiff, DiffStatus, DiffOptions, DiffStats, DiffChunk, DiffLine, DiffLineType (in src/commands/diff.rs), Tag, TagList, TagType, TagOptions (in src/commands/tag.rs), Stash, StashList, StashOptions, StashApplyOptions (in src/commands/stash.rs)
 - **Utility functions**: git(args, working_dir) -> Result<String>, git_raw(args, working_dir) -> Result<Output>
 - **Remote management**: Full remote operations with network support
   - Repository::add_remote(name, url) -> Result<()> - add remote repository
@@ -110,8 +110,21 @@
   - TagList: Box<[Tag]> with iterator methods (iter, lightweight, annotated), search (find, find_containing, for_commit), counting (len, lightweight_count, annotated_count)
   - TagOptions builder: annotated, force, message, sign with builder pattern (with_annotated, with_force, with_message, with_sign)
   - Author struct: name, email, timestamp for annotated tag metadata
-- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs, remote.rs, files.rs, diff.rs, tag.rs (in src/commands/)
-- **Testing**: 152+ tests covering all functionality with comprehensive edge cases
+- **Stash operations**: Complete stash management with type-safe API
+  - Repository::stash_list() -> Result<StashList> - list all stashes with comprehensive filtering
+  - Repository::stash_save(message) -> Result<Stash> - create simple stash
+  - Repository::stash_push(message, options) -> Result<Stash> - create stash with options
+  - Repository::stash_apply(index, options) -> Result<()> - apply stash without removing it
+  - Repository::stash_pop(index, options) -> Result<()> - apply and remove stash
+  - Repository::stash_show(index) -> Result<String> - show stash contents
+  - Repository::stash_drop(index) -> Result<()> - remove specific stash
+  - Repository::stash_clear() -> Result<()> - remove all stashes
+  - Stash struct: index, message, hash, branch, timestamp
+  - StashList: Box<[Stash]> with iterator methods (iter), search (find_containing, for_branch), access (latest, get), counting (len, is_empty)
+  - StashOptions builder: untracked, keep_index, patch, staged_only, paths with builder pattern (with_untracked, with_keep_index, with_patch, with_staged_only, with_paths)
+  - StashApplyOptions builder: restore_index, quiet with builder pattern (with_index, with_quiet)
+- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs, remote.rs, files.rs, diff.rs, tag.rs, stash.rs (in src/commands/)
+- **Testing**: 161+ tests covering all functionality with comprehensive edge cases
 - Run `cargo fmt && cargo build && cargo test && cargo clippy --all-targets --all-features -- -D warnings` after code changes
 - Make sure all examples are running
 
@@ -130,6 +143,7 @@ The `examples/` directory contains comprehensive demonstrations of library funct
 - **file_lifecycle_operations.rs**: Comprehensive file management - restore/reset/remove/move operations, .gitignore management, advanced file lifecycle workflows, staging area manipulation
 - **diff_operations.rs**: Comprehensive diff operations showcase - unstaged/staged diffs, commit comparisons, advanced options (whitespace handling, path filtering), output formats (name-only, stat, numstat), and change analysis
 - **tag_operations.rs**: Complete tag management - create/delete/list tags, lightweight vs annotated tags, TagOptions builder, tag filtering and search, comprehensive tag workflows
+- **stash_operations.rs**: Complete stash management - save/apply/pop/list stashes, advanced options (untracked files, keep index, specific paths), stash filtering and search, comprehensive stash workflows
 - **error_handling.rs**: Comprehensive error handling patterns - GitError variants, recovery strategies
 
 Run examples with: `cargo run --example <example_name>`

PLAN.md

@@ -17,6 +17,7 @@
 - **File lifecycle operations (restore, reset, remove, move, .gitignore management)**
 - **Diff operations with multi-level API and comprehensive options**
 - **Tag management with comprehensive operations and filtering**
+- **Stash operations with comprehensive management and filtering**
 
 ## ✅ Phase 1: Essential Remote Operations (COMPLETED)
 
@@ -76,21 +77,28 @@
 - [x] Type-safe TagType enum (Lightweight, Annotated)
 - [x] Complete tag metadata support (message, tagger, timestamp)
 
-## Phase 4: Release Management (Medium Priority)
+## Phase 5: Release Management (Medium Priority)
 
 ### Archive & Export
 - [ ] `repo.archive(format, output_path)` - Create repository archive
 - [ ] `repo.export_commit(hash, path)` - Export specific commit
 
-## Phase 5: Development Workflow (Medium Priority)
+## ✅ Phase 4: Stash Operations (COMPLETED)
 
-### Stash Management
-- [ ] `repo.stash_save(message)` - Save current changes
-- [ ] `repo.stash_push(files, message)` - Stash specific files
-- [ ] `repo.stash_list()` - List all stashes
-- [ ] `repo.stash_pop()` / `repo.stash_apply(index)` - Apply stashes
-- [ ] `repo.stash_drop(index)` / `repo.stash_clear()` - Remove stashes
-- [ ] `repo.stash_show(index)` - Show stash contents
+### ✅ Stash Management
+- [x] `repo.stash_save(message)` - Save current changes
+- [x] `repo.stash_push(message, options)` - Stash with advanced options
+- [x] `repo.stash_list()` - List all stashes with comprehensive filtering
+- [x] `repo.stash_apply(index, options)` - Apply stash without removing it
+- [x] `repo.stash_pop(index, options)` - Apply and remove stash
+- [x] `repo.stash_drop(index)` / `repo.stash_clear()` - Remove stashes
+- [x] `repo.stash_show(index)` - Show stash contents
+- [x] StashList with filtering (find_containing, for_branch, latest, get)
+- [x] StashOptions builder with untracked, keep_index, patch, staged_only, paths
+- [x] StashApplyOptions builder with restore_index, quiet options
+- [x] Complete stash metadata support (index, message, hash, branch, timestamp)
+
+## Phase 6: Development Workflow (Medium Priority)
 
 ### Merge & Rebase
 - [ ] `repo.merge(branch)` / `repo.merge_commit(hash)` - Merge operations
@@ -99,7 +107,7 @@
 - [ ] Conflict resolution helpers and status
 - [ ] `repo.abort_merge()` / `repo.abort_rebase()` - Abort operations
 
-## Phase 6: Advanced Configuration (Medium Priority)
+## Phase 7: Advanced Configuration (Medium Priority)
 
 ### Enhanced Configuration
 - [ ] `Config::global()` - Global git configuration
@@ -114,7 +122,7 @@
 - [ ] `repo.hooks().remove(hook_type)` - Remove hooks
 - [ ] Pre-built common hooks (pre-commit, pre-push, etc.)
 
-## Phase 7: Repository Analysis (Low Priority)
+## Phase 8: Repository Analysis (Low Priority)
 
 ### History & Inspection
 - [ ] `repo.show(hash)` - Show commit with full diff
@@ -128,7 +136,7 @@
 - [ ] `repo.size_analysis()` - Large files, repository size analysis
 - [ ] `repo.gc()` / `repo.fsck()` - Maintenance operations
 
-## Phase 8: Advanced Features (Low Priority)
+## Phase 9: Advanced Features (Low Priority)
 
 ### Worktree Support
 - [ ] `repo.worktree_add(path, branch)` - Add worktree