Skip to content

PLAN.md

Latest commit

 

History

History
253 lines (204 loc) · 10 KB

PLAN.md

File metadata and controls

253 lines (204 loc) · 10 KB

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)
  • Diff operations with multi-level API and comprehensive options
  • Tag management with comprehensive operations and filtering
  • Stash operations with comprehensive management and filtering
  • Reset operations with comprehensive reset modes and error handling

##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: Tag Operations (COMPLETED)

###Tag Management

  • [x]repo.tags() - List all tags with comprehensive filtering
  • [x]repo.create_tag(name, target) - Create lightweight tag
  • [x]repo.create_tag_with_options(name, target, options) - Create tag with options
  • [x]repo.delete_tag(name) - Delete tag
  • [x]repo.show_tag(name) - Get detailed tag information
  • [x]TagList with filtering (lightweight, annotated, find_containing, for_commit)
  • [x]TagOptions builder with force, message, sign, annotated options
  • [x]Type-safe TagType enum (Lightweight, Annotated)
  • [x]Complete tag metadata support (message, tagger, timestamp)

##Phase 4: Stash Operations (COMPLETED)

###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 5: Reset Operations (COMPLETED)

###Reset Management

  • [x]repo.reset_soft(commit) - Move HEAD, keep index and working tree
  • [x]repo.reset_mixed(commit) - Move HEAD, reset index, keep working tree (default)
  • [x]repo.reset_hard(commit) - Reset HEAD, index, and working tree to commit state
  • [x]repo.reset_with_mode(commit, mode) - Flexible reset with explicit ResetMode
  • [x]repo.reset_file(path) - Unstage specific file (already exists in files.rs)
  • [x]ResetMode enum with type-safe mode selection (Soft, Mixed, Hard)
  • [x]Complete error handling for invalid commits and references
  • [x]Comprehensive reset workflows with file-specific operations
  • [x]Cross-platform temporary directory handling for tests

##Phase 6: Merge Operations (COMPLETED)

###Merge Management

  • [x]repo.merge(branch) - Merge branch into current branch
  • [x]repo.merge_with_options(branch, options) - Merge with advanced options
  • [x]repo.merge_in_progress() - Check if merge is currently in progress
  • [x]repo.abort_merge() - Cancel ongoing merge operation
  • [x]MergeStatus enum with Success, FastForward, UpToDate, Conflicts variants
  • [x]MergeOptions builder with fast_forward, strategy, commit_message, no_commit options
  • [x]FastForwardMode enum: Auto, Only, Never with const as_str() methods
  • [x]MergeStrategy enum: Recursive, Ours, Theirs with const as_str() methods
  • [x]Complete conflict detection with file-level granularity
  • [x]Comprehensive merge workflows with error handling

Phase 7: Release Management (Medium Priority)

Archive & Export

  • repo.archive(format, output_path) - Create repository archive
  • repo.export_commit(hash, path) - Export specific commit

Phase 8: Development Workflow (Medium Priority)

Rebase & Cherry-pick

  • repo.rebase(onto_branch) - Rebase current branch
  • repo.cherry_pick(hash) - Cherry-pick commit
  • repo.abort_rebase() - Abort rebase operations

Phase 9: 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 10: 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 11: 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.