Merge pull request #8 from eugener/develop

Comprehensive diff operations API

Author: eugener

CLAUDE.md

@@ -56,10 +56,51 @@
   - 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)
+- **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)
 - **Utility functions**: git(args, working_dir) -> Result<String>, git_raw(args, working_dir) -> Result<Output>
-- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs (in src/commands/)
-- **Testing**: 106+ tests covering all functionality with comprehensive edge cases
+- **Remote management**: Full remote operations with network support
+  - Repository::add_remote(name, url) -> Result<()> - add remote repository
+  - Repository::remove_remote(name) -> Result<()> - remove remote
+  - Repository::rename_remote(old_name, new_name) -> Result<()> - rename remote
+  - Repository::list_remotes() -> Result<RemoteList> - list all remotes with URLs
+  - Repository::get_remote_url(name) -> Result<String> - get remote URL
+  - Repository::fetch(remote) -> Result<()> - fetch from remote repository
+  - Repository::fetch_with_options(remote, options) -> Result<()> - fetch with FetchOptions
+  - Repository::push(remote, branch) -> Result<()> - push to remote repository
+  - Repository::push_with_options(remote, branch, options) -> Result<()> - push with PushOptions
+  - Repository::clone(url, path) -> Result<Repository> - clone repository (static method)
+  - Remote struct: name, fetch_url, push_url with proper URL handling
+  - RemoteList: Vec<Remote> with search methods (find, iter, len, is_empty)
+  - FetchOptions: prune, tags, all_remotes with builder pattern (with_prune, with_tags, with_all_remotes)
+  - PushOptions: force, tags, set_upstream with builder pattern (with_force, with_tags, with_set_upstream)
+- **File lifecycle operations**: Comprehensive file management with advanced options
+  - Repository::checkout_file(path) -> Result<()> - restore file from HEAD
+  - Repository::restore(paths, options) -> Result<()> - advanced restore with RestoreOptions
+  - Repository::reset_file(path) -> Result<()> - unstage specific file
+  - Repository::rm(paths) -> Result<()> - remove files from repository
+  - Repository::rm_with_options(paths, options) -> Result<()> - remove with RemoveOptions
+  - Repository::mv(source, destination) -> Result<()> - move/rename files
+  - Repository::mv_with_options(source, dest, options) -> Result<()> - move with MoveOptions
+  - Repository::ignore_add(patterns) -> Result<()> - add patterns to .gitignore
+  - Repository::ignore_check(path) -> Result<bool> - check if file is ignored
+  - Repository::ignore_list() -> Result<Vec<String>> - list current ignore patterns
+  - RestoreOptions: with_source(), with_staged(), with_worktree() - builder for restore configuration
+  - RemoveOptions: with_force(), with_recursive(), with_cached(), with_ignore_unmatch() - builder for remove configuration
+  - MoveOptions: with_force(), with_verbose(), with_dry_run() - builder for move configuration
+- **Diff operations**: Multi-level API for comprehensive change comparison
+  - Repository::diff() -> Result<DiffOutput> - working directory vs index (unstaged changes)
+  - Repository::diff_staged() -> Result<DiffOutput> - index vs HEAD (staged changes)
+  - Repository::diff_head() -> Result<DiffOutput> - working directory vs HEAD (all changes)
+  - Repository::diff_commits(from, to) -> Result<DiffOutput> - between specific commits
+  - Repository::diff_with_options(options) -> Result<DiffOutput> - advanced diff with DiffOptions
+  - DiffOutput: files, stats with immutable collections and comprehensive filtering
+  - FileDiff: path, old_path, status, chunks, additions, deletions with change details
+  - DiffStatus enum: Added, Modified, Deleted, Renamed, Copied with const char conversion
+  - DiffOptions: context_lines, whitespace handling, path filtering, output formats (name-only, stat, numstat)
+  - DiffStats: files_changed, insertions, deletions with aggregate statistics
+  - Complete filtering: files_with_status(), iter(), is_empty(), len() for result analysis
+- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs, remote.rs, files.rs, diff.rs (in src/commands/)
+- **Testing**: 144+ 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
 
@@ -73,6 +114,10 @@ The `examples/` directory contains comprehensive demonstrations of library funct
 - **commit_workflows.rs**: Commit operations and Hash type - commit(), commit_with_author(), Hash methods
 - **branch_operations.rs**: Complete branch management - create/delete/checkout branches, BranchList filtering, branch type handling, search operations
 - **commit_history.rs**: Comprehensive commit history & log operations - demonstrates all commit querying APIs, filtering, analysis, and advanced LogOptions usage
+- **config_operations.rs**: Repository configuration management - user setup, configuration values, repository-scoped settings
+- **remote_operations.rs**: Complete remote management - add/remove/rename remotes, fetch/push operations with options, network operations, error handling
+- **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
 - **error_handling.rs**: Comprehensive error handling patterns - GitError variants, recovery strategies
 
 Run examples with: `cargo run --example <example_name>`

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rustic-git"
-version = "0.2.1"
+version = "0.3.0"
 edition = "2024"
 license = "MIT"
 description = "A Rustic Git - clean type-safe API over git cli"

Cargo.toml

@@ -0,0 +1,212 @@
+# Rustic Git - Development Plan
+
+## Current Status
+
+✅ **Completed Core Features**
+- Repository initialization and opening
+- Enhanced file status checking with staged/unstaged tracking
+- Staging operations (add, add_all, add_update)
+- Commit operations with custom authors
+- Branch operations (create, checkout, delete, list)
+- Configuration management (user settings, repository config)
+- Commit history and log operations with filtering
+- Error handling with comprehensive GitError types
+- Cross-platform compatibility (OS-agnostic temp directories)
+- **Remote management with full CRUD operations**
+- **Network operations (fetch, push, clone) with advanced options**
+- **File lifecycle operations (restore, reset, remove, move, .gitignore management)**
+
+## ✅ Phase 1: Essential Remote Operations (COMPLETED)
+
+### ✅ Remote Management
+- [x] `repo.add_remote(name, url)` - Add remote repository
+- [x] `repo.remove_remote(name)` - Remove remote
+- [x] `repo.list_remotes()` - List all remotes with URLs
+- [x] `repo.rename_remote(old_name, new_name)` - Rename remote
+- [x] `repo.get_remote_url(name)` - Get remote URL
+
+### ✅ Network Operations
+- [x] `repo.fetch(remote)` / `repo.fetch_with_options()` - Fetch from remotes
+- [x] `repo.push(remote, branch)` / `repo.push_with_options()` - Push changes
+- [x] `repo.clone(url, path)` - Clone repository (static method)
+- [x] Advanced options with FetchOptions and PushOptions
+- [x] Type-safe builder patterns for network operations
+
+## ✅ Phase 2: File Lifecycle Operations (COMPLETED)
+
+### ✅ File Management
+- [x] `repo.checkout_file(path)` - Restore file from HEAD
+- [x] `repo.reset_file(path)` - Unstage specific file
+- [x] `repo.rm(paths)` - Remove files from repository
+- [x] `repo.rm_with_options(paths, options)` - Remove with advanced options
+- [x] `repo.mv(from, to)` - Move/rename files in repository
+- [x] `repo.mv_with_options(source, dest, options)` - Move with advanced options
+- [x] `repo.restore(paths, options)` - Restore files from specific commit with advanced options
+
+### ✅ Ignore Management
+- [x] `repo.ignore_add(patterns)` - Add patterns to .gitignore
+- [x] `repo.ignore_check(file)` - Check if file is ignored
+- [x] `repo.ignore_list()` - List current ignore patterns
+
+### ✅ Advanced File Operations
+- [x] RestoreOptions with source, staged, and worktree control
+- [x] RemoveOptions with force, recursive, cached, and ignore-unmatch
+- [x] MoveOptions with force, verbose, and dry-run modes
+- [x] Type-safe builder patterns for all file operations
+
+### 🔄 Remote Branch Tracking (Future Enhancement)
+- [ ] `repo.branch_set_upstream(branch, remote_branch)` - Set tracking
+- [ ] `repo.branch_track(local, remote)` - Track remote branch
+- [ ] Remote branch listing and status
+- [ ] Pull operations (fetch + merge)
+
+
+## Phase 3: Release Management (Medium Priority)
+
+### Tag Operations
+- [ ] `repo.create_tag(name, message)` - Create annotated tag
+- [ ] `repo.create_lightweight_tag(name)` - Create lightweight tag
+- [ ] `repo.list_tags()` - List tags with filtering options
+- [ ] `repo.delete_tag(name)` - Delete tag
+- [ ] `repo.tag_info(name)` - Get tag details
+- [ ] `repo.push_tags()` - Push tags to remote
+
+### Archive & Export
+- [ ] `repo.archive(format, output_path)` - Create repository archive
+- [ ] `repo.export_commit(hash, path)` - Export specific commit
+
+## Phase 4: Development Workflow (Medium Priority)
+
+### 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
+
+### Merge & Rebase
+- [ ] `repo.merge(branch)` / `repo.merge_commit(hash)` - Merge operations
+- [ ] `repo.rebase(onto_branch)` - Rebase current branch
+- [ ] `repo.cherry_pick(hash)` - Cherry-pick commit
+- [ ] Conflict resolution helpers and status
+- [ ] `repo.abort_merge()` / `repo.abort_rebase()` - Abort operations
+
+## Phase 5: Advanced Configuration (Medium Priority)
+
+### Enhanced Configuration
+- [ ] `Config::global()` - Global git configuration
+- [ ] `Config::system()` - System-wide configuration
+- [ ] Config scopes (system, global, local)
+- [ ] `repo.config().list_all()` - List all config with scopes
+- [ ] `repo.config().edit()` - Interactive config editing
+
+### Hook Management
+- [ ] `repo.hooks().install(hook_type, script)` - Install git hooks
+- [ ] `repo.hooks().list()` - List installed hooks
+- [ ] `repo.hooks().remove(hook_type)` - Remove hooks
+- [ ] Pre-built common hooks (pre-commit, pre-push, etc.)
+
+## Phase 6: Repository Analysis (Low Priority)
+
+### History & Inspection
+- [ ] `repo.show(hash)` - Show commit with full diff
+- [ ] `repo.blame(file, line_range)` - File annotation
+- [ ] `repo.diff(from, to)` - Diff between commits/branches
+- [ ] `repo.diff_files(from, to, paths)` - Diff specific files
+
+### Repository Health
+- [ ] `repo.statistics()` - Commit count, contributors, file stats
+- [ ] `repo.health_check()` - Repository integrity check
+- [ ] `repo.size_analysis()` - Large files, repository size analysis
+- [ ] `repo.gc()` / `repo.fsck()` - Maintenance operations
+
+## Phase 7: Advanced Features (Low Priority)
+
+### Worktree Support
+- [ ] `repo.worktree_add(path, branch)` - Add worktree
+- [ ] `repo.worktree_list()` - List worktrees
+- [ ] `repo.worktree_remove(path)` - Remove worktree
+
+### Batch Operations
+- [ ] `repo.batch()` - Transaction-like operations
+- [ ] Bulk file operations with progress callbacks
+- [ ] Atomic multi-step operations
+
+### Integration Helpers
+- [ ] Workspace detection (Cargo.toml, package.json, etc.)
+- [ ] CI/CD integration helpers
+- [ ] Git flow / GitHub flow shortcuts
+- [ ] Semantic versioning helpers
+
+## API Design Principles
+
+### Consistency
+- Repository-centric design: operations as methods on `Repository`
+- Consistent error handling with `Result<T, GitError>`
+- Type-safe enums for status, branch types, etc.
+- Builder patterns for complex operations with options
+
+### Performance
+- Lazy evaluation where possible
+- Streaming for large operations
+- Progress callbacks for long-running operations
+- Efficient caching of git command results
+
+### Ergonomics
+- Sensible defaults for common use cases
+- Method chaining where appropriate
+- Clear, descriptive method names
+- Comprehensive documentation with examples
+
+## Quality Standards
+
+### Testing
+- Unit tests for all public APIs
+- Integration tests with real git repositories
+- Cross-platform testing (Windows, macOS, Linux)
+- Performance benchmarks for critical operations
+
+### Documentation
+- Comprehensive rustdoc for all public APIs
+- Example code in documentation
+- Example programs in `examples/` directory
+- Clear error messages and recovery suggestions
+
+### Compatibility
+- Support latest stable Rust (currently 1.89+)
+- Cross-platform file path handling
+- Graceful handling of different git versions
+- Consistent behavior across operating systems
+
+## Implementation Notes
+
+### Technical Decisions
+- Continue using `std::process::Command` for git operations
+- Maintain clean separation between core types and command modules
+- Use `PathBuf` for all path operations for cross-platform compatibility
+- Implement `From` traits for ergonomic type conversions
+
+### Breaking Changes
+- Follow semantic versioning strictly
+- Deprecate before removing APIs
+- Provide migration guides for major version updates
+- Maintain backwards compatibility within major versions
+
+## Success Metrics
+
+### Adoption
+- Crates.io download counts
+- GitHub stars and forks
+- Community contributions and issues
+- Integration in other Rust projects
+
+### Quality
+- Test coverage > 90%
+- Documentation coverage 100%
+- Zero clippy warnings
+- Fast CI/CD pipeline (< 5 minutes)
+
+---
+
+*This plan will be updated as features are implemented and priorities shift based on community feedback.*