feat(merge): implement comprehensive merge operations

Add complete merge functionality including fast-forward/no-fast-forward merges,
conflict detection and handling, merge status tracking, and abort operations
with comprehensive example and documentation updates

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), Stash, StashList, StashOptions, StashApplyOptions (in src/commands/stash.rs), ResetMode (in src/commands/reset.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), ResetMode (in src/commands/reset.rs), MergeStatus, MergeOptions, FastForwardMode, MergeStrategy (in src/commands/merge.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
@@ -131,8 +131,18 @@
   - Repository::reset_file(path) -> Result<()> - unstage specific file (already exists in files.rs)
   - ResetMode enum: Soft, Mixed, Hard with const as_str() methods
   - Complete error handling for invalid commits and references
-- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs, remote.rs, files.rs, diff.rs, tag.rs, stash.rs, reset.rs (in src/commands/)
-- **Testing**: 178+ tests covering all functionality with comprehensive edge cases
+- **Merge operations**: Complete merge functionality with comprehensive conflict handling
+  - Repository::merge(branch) -> Result<MergeStatus> - merge branch into current branch
+  - Repository::merge_with_options(branch, options) -> Result<MergeStatus> - merge with advanced options
+  - Repository::merge_in_progress() -> Result<bool> - check if merge is currently in progress
+  - Repository::abort_merge() -> Result<()> - cancel ongoing merge operation
+  - MergeStatus enum: Success(Hash), FastForward(Hash), UpToDate, Conflicts(Vec<PathBuf>) with comprehensive status tracking
+  - MergeOptions builder: fast_forward, strategy, commit_message, no_commit with builder pattern (with_fast_forward, with_strategy, with_message, with_no_commit)
+  - FastForwardMode enum: Auto, Only, Never with const as_str() methods
+  - MergeStrategy enum: Recursive, Ours, Theirs with const as_str() methods
+  - Complete conflict detection with file-level granularity
+- **Command modules**: status.rs, add.rs, commit.rs, branch.rs, log.rs, config.rs, remote.rs, files.rs, diff.rs, tag.rs, stash.rs, reset.rs, merge.rs (in src/commands/)
+- **Testing**: 187+ 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
 
@@ -153,6 +163,7 @@ The `examples/` directory contains comprehensive demonstrations of library funct
 - **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
 - **reset_operations.rs**: Complete reset management - soft/mixed/hard resets, commit targeting, file-specific resets, error handling for invalid commits, comprehensive reset workflows
+- **merge_operations.rs**: Complete merge management - fast-forward/no-fast-forward merges, conflict detection and handling, merge status checking, abort operations, comprehensive merge workflows
 - **error_handling.rs**: Comprehensive error handling patterns - GitError variants, recovery strategies
 
 Run examples with: `cargo run --example <example_name>`

PLAN.md

@@ -2,7 +2,7 @@
 
 ## Current Status
 
-✅ **Completed Core Features**
+**Completed Core Features**
 - Repository initialization and opening
 - Enhanced file status checking with staged/unstaged tracking
 - Staging operations (add, add_all, add_update)
@@ -20,108 +20,120 @@
 - **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)
+##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: Release Management (Medium Priority)
+##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 7: Development Workflow (Medium Priority)
+## Phase 8: Development Workflow (Medium Priority)
 
-### Merge & Rebase
-- [ ] `repo.merge(branch)` / `repo.merge_commit(hash)` - Merge operations
+### Rebase & Cherry-pick
 - [ ] `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
+- [ ] `repo.abort_rebase()` - Abort rebase operations
 
-## Phase 8: Advanced Configuration (Medium Priority)
+## Phase 9: Advanced Configuration (Medium Priority)
 
 ### Enhanced Configuration
 - [ ] `Config::global()` - Global git configuration
@@ -136,7 +148,7 @@
 - [ ] `repo.hooks().remove(hook_type)` - Remove hooks
 - [ ] Pre-built common hooks (pre-commit, pre-push, etc.)
 
-## Phase 9: Repository Analysis (Low Priority)
+## Phase 10: Repository Analysis (Low Priority)
 
 ### History & Inspection
 - [ ] `repo.show(hash)` - Show commit with full diff
@@ -150,7 +162,7 @@
 - [ ] `repo.size_analysis()` - Large files, repository size analysis
 - [ ] `repo.gc()` / `repo.fsck()` - Maintenance operations
 
-## Phase 10: Advanced Features (Low Priority)
+## Phase 11: Advanced Features (Low Priority)
 
 ### Worktree Support
 - [ ] `repo.worktree_add(path, branch)` - Add worktree

README.md

@@ -16,31 +16,33 @@ Rustic Git provides a simple, ergonomic interface for common Git operations. It
 
 ## Features
 
-- ✅ Repository initialization and opening
-- ✅ **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
-- ✅ **Complete branch operations** with type-safe Branch API
-- ✅ **Branch management** (create, delete, checkout, list)
-- ✅ **Commit history & log operations** with multi-level API
-- ✅ **Advanced commit querying** with filtering and analysis
-- ✅ **Repository configuration management** with type-safe API
-- ✅ **Remote management** with full CRUD operations and network support
-- ✅ **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
-- ✅ **Lightweight and annotated tags** with type-safe API
-- ✅ **Stash operations** with comprehensive stash management and filtering
-- ✅ **Advanced stash options** (untracked files, keep index, specific paths)
-- ✅ **Reset operations** with comprehensive soft/mixed/hard reset support
-- ✅ **Repository history management** with type-safe ResetMode API
-- ✅ Type-safe error handling with custom GitError enum
-- ✅ Universal `Hash` type for Git objects
-- ✅ **Immutable collections** (Box<[T]>) for memory efficiency
-- ✅ **Const enum conversions** with zero runtime cost
-- ✅ Comprehensive test coverage (161+ tests)
+-Repository initialization and opening
+-**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
+-**Complete branch operations** with type-safe Branch API
+-**Branch management** (create, delete, checkout, list)
+-**Commit history & log operations** with multi-level API
+-**Advanced commit querying** with filtering and analysis
+-**Repository configuration management** with type-safe API
+-**Remote management** with full CRUD operations and network support
+-**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
+-**Lightweight and annotated tags** with type-safe API
+-**Stash operations** with comprehensive stash management and filtering
+-**Advanced stash options** (untracked files, keep index, specific paths)
+-**Reset operations** with comprehensive soft/mixed/hard reset support
+-**Repository history management** with type-safe ResetMode API
+-**Merge operations** with comprehensive branch merging and conflict handling
+-**Advanced merge options** (fast-forward control, merge strategies, conflict detection)
+-Type-safe error handling with custom GitError enum
+-Universal `Hash` type for Git objects
+-**Immutable collections** (Box<[T]>) for memory efficiency
+-**Const enum conversions** with zero runtime cost
+-Comprehensive test coverage (187+ tests)
 
 ## Installation