Resolve Conflicts

Git Conflict Resolution

Resolve Git merge conflicts by intelligently combining changes from both branches while preserving the intent of both changes. This skill follows a plan-first approach: assess conflicts, create a detailed resolution plan, get approval, then execute.

Core Principles

1. Plan Before Executing: Always create a structured resolution plan and get user approval before making changes 2. Prefer Both Changes: Default to keeping both changes unless they directly contradict 3. Merge, Don't Choose: Especially for imports, tests, and configuration 4. Regenerate Generated Files: Never manually merge generated files - always regenerate them from their sources 5. Backup Before Resolving: For deleted-modified files, create backups first 6. Validate with Tests: Always run tests after resolution 7. Explain All Resolutions: For each conflict resolved, provide a one-line explanation of the resolution strategy 8. Ask When Unclear: When the correct resolution isn't clear from the diff, present options to the user and ask for their choice

Workflow

Step 1: Assess the Conflict Situation

Run initial checks to understand the conflict scope:

git status

Identify and categorize all conflicted files:

• Regular file conflicts (both modified)
• Deleted-modified conflicts (one deleted, one modified)
• Generated file conflicts (lock files, build artifacts, generated code)
• Test file conflicts
• Import/configuration conflicts
• Binary file conflicts

For each conflicted file, gather information:

• File type and purpose
• Nature of the conflict (content, deletion, type change)
• Scope of changes (lines changed, sections affected)
• Whether the file is generated or hand-written

Step 2: Create Merge Resolution Plan

Based on the assessment, create a structured plan before resolving any conflicts. Present the plan in the following markdown format:

## Merge Resolution Plan

### Conflict Summary

- **Total conflicted files**: [N]
- **Deleted-modified conflicts**: [N]
- **Generated files**: [N]
- **Regular conflicts**: [N]

### Resolution Strategy by File

#### 1. [File Path]

**Conflict Type**: [deleted-modified / generated / imports / tests / code logic / config / struct / binary]
**Strategy**: [Brief description of resolution approach]
**Rationale**: [Why this strategy is appropriate]
**Risk**: [Low/Medium/High] - [Brief risk description]
**Action Items**:

- [ ] [Specific action 1]
- [ ] [Specific action 2]

#### 2. [File Path]

...

### Execution Order

1. **Phase 1: Deleted-Modified Files** - Handle deletions and backups first
2. **Phase 2: Generated Files** - Regenerate from source
3. **Phase 3: Low-Risk Merges** - Imports, tests, documentation
4. **Phase 4: High-Risk Merges** - Code logic, configuration, structs
5. **Phase 5: Validation** - Compile, test, verify

### Questions/Decisions Needed

- [ ] **[File/Decision]**: [Question for user] (Options: 1, 2, 3)

### Validation Steps

- [ ] Run conflict validation script
- [ ] Compile project
- [ ] Run test suite
- [ ] Manual verification of high-risk changes

Present this plan to the user and wait for their approval before proceeding with resolution. If there are any unclear conflicts where you need user input, list them in the "Questions/Decisions Needed" section.

For a complete example plan, see references/sample-plan.md.

Step 3: Handle Deleted-Modified Files

Execute this phase only after the plan is approved.

If there are deleted-but-modified files (status: DU, UD, DD, UA, AU):

.forge/skills/resolve-conflicts/scripts/handle-deleted-modified.sh

This script will:

• Create timestamped backups of modified content
• Analyze potential relocation targets
• Generate analysis reports for each file
• Automatically resolve the deletion status

Review the backup directory and analysis files to understand where changes should be applied.

Step 4: Execute Resolution Plan

Follow the execution order defined in your plan. For each conflicted file, apply the appropriate resolution pattern according to your plan. For every conflict you resolve, provide a one-line explanation of how you're resolving it.

As you complete each action item in your plan, mark it as done and report progress to the user.

When Resolution is Unclear

When you cannot determine the correct resolution from the diff alone (these should already be listed in your plan's "Questions/Decisions Needed" section):

1. Present the conflict to the user with the conflicting code from both sides 2. Provide numbered options for resolution (Option 1, Option 2, etc.) 3. Explain each option clearly with what it would do 4. Ask the user to choose an option number or provide additional information 5. Remember their choice and apply similar reasoning to subsequent related conflicts

Example interaction:

I found a conflict in src/main.rs where both branches modify the `calculate_price` function:

<<<<<<< HEAD (Current Branch)
fn calculate_price(item: &Item) -> f64 {
    item.base_price * (1.0 + item.tax_rate)
}
=======
fn calculate_price(item: &Item) -> f64 {
    item.base_price + item.tax_amount
}
>>>>>>> feature-branch (Incoming Branch)

I'm not sure which calculation is correct. Please select an option:

**Option 1**: Keep current branch (multiplies base_price by tax_rate)
**Option 2**: Keep incoming branch (adds tax_amount to base_price)
**Option 3**: Keep both approaches with a new parameter
**Option 4**: Provide more context to help me decide

Please respond with "Option 1", "Option 2", "Option 3", or "Option 4", or provide additional information.

Once the user responds, apply their decision and similar logic to related conflicts.

Resolution Patterns

For each conflicted file, apply the appropriate resolution pattern:

Imports/Dependencies

Goal: Merge all unique imports from both branches.

One-line explanation: "Merging imports by combining unique imports from both branches, removing duplicates, and grouping by module."

Read references/patterns.md section "Import Conflicts" for detailed examples.

Quick approach:

1. Extract all imports from both sides 2. Remove duplicates 3. Group by module/package 4. Follow language-specific style (alphabetize, group std/external/internal)

Tests

Goal: Include all test cases and test data from both branches.

One-line explanation: "Merging tests by including all test cases from both branches, combining fixtures, and renaming if necessary to avoid conflicts."

Read references/patterns.md section "Test Conflicts" for detailed examples.

Quick approach:

1. Keep all test functions unless they test the exact same thing 2. Merge test fixtures and setup functions 3. Combine assertions from both sides 4. If test names conflict but test different behaviors, rename to clarify

Generated Files

Goal: Regenerate any generated files to include changes from both branches.

One-line explanation: "Resolving generated file by regenerating it from source files to incorporate changes from both branches."

Recognition: A file is generated if it:

• Is produced by a build tool, compiler, or code generator
• Has a source file or configuration that defines it
• Contains headers/comments indicating it's auto-generated
• Is listed in .gitattributes as generated
• Common examples: lock files, protobuf outputs, GraphQL schema files, compiled assets, auto-generated docs

Approach:

1. Identify the generation source: Determine what command or tool generates the file 2. Choose either version temporarily (doesn't matter which):

   git checkout --ours <generated-file>    # or --theirs

3. Regenerate from source: Run the appropriate generation command:

   # Package manager lock files
   cargo update                       # for Cargo.lock
   npm install                        # for package-lock.json
   yarn install                       # for yarn.lock
   bundle install                     # for Gemfile.lock
   poetry lock --no-update            # for poetry.lock

   # Code generation
   protoc ...                         # for protobuf files
   graphql-codegen                    # for GraphQL generated code
   make generate                      # for Makefile-based generation
   npm run generate                   # for npm script-based generation

   # Build artifacts
   npm run build                      # for compiled/bundled assets
   cargo build                        # for Rust build artifacts

4. Stage the regenerated file:

   git add <generated-file>

When unsure if a file is generated: Check for auto-generation markers in the file header, or ask the user if you should regenerate or manually merge the file.

Configuration Files

Goal: Merge configuration values from both branches.

One-line explanation: "Merging configuration by including all keys from both branches and choosing appropriate values for conflicts."

Read references/patterns.md section "Configuration File Conflicts" for detailed examples.

Quick approach:

1. Include all keys from both sides 2. For conflicting values, choose based on:

• Newer/more recent value
• Safer/more conservative value
• Production requirements

3. Document choice in commit message

When unclear: Ask the user which configuration value to prefer (current vs incoming)

Code Logic

Goal: Understand intent of both changes and combine if possible.

One-line explanation: "Resolving code logic by analyzing intent: merging if changes are orthogonal, or choosing one approach if they conflict."

Read references/patterns.md section "Code Logic Conflicts" for detailed examples.

Quick approach:

1. Analyze what each branch is trying to achieve 2. If changes are orthogonal (different concerns), merge both 3. If changes conflict (same concern, different approach):

• Review commit messages/PRs for context
• Choose the approach that matches requirements
• Test both approaches if unclear
• Document the decision

When unclear: Present both approaches as options to the user with context about what each does

Struct/Type Definitions

Goal: Include all fields from both branches.

One-line explanation: "Merging struct by including all fields from both branches and choosing appropriate types for any conflicting field definitions."

Quick approach:

1. Merge all fields 2. If field types conflict, analyze which is more appropriate 3. Fix all compilation errors from updated struct 4. Update tests to use new fields

When unclear: Ask the user which type definition is correct if field types conflict

Step 5: Validate Resolution

After completing all resolution phases in your plan, validate that all conflicts are resolved:

.forge/skills/resolve-conflicts/scripts/validate-conflicts.sh

This script checks for:

• Remaining conflict markers (<<<<<<<, =======, >>>>>>>)
• Unmerged paths in git status
• Deleted-modified conflicts
• Merge state files

Step 6: Compile and Test

Build and test to ensure the resolution is correct (as defined in your plan's validation steps):

# For Rust projects
cargo test

# For other projects, use appropriate test command
# npm test
# pytest
# etc.

If tests fail:

1. Review the failure - is it from merged code or conflict resolution? 2. Check if both branches' tests pass individually 3. Fix integration issues between the merged changes 4. Re-run tests until all pass

Step 7: Finalize

Once all conflicts are resolved and tests pass, review your completed plan and commit:

# Review the changes
git diff --cached

# Commit with descriptive message that references the plan
git commit -m "Resolve merge conflicts: [describe key decisions]

Executed merge resolution plan:
- [Phase 1 summary]
- [Phase 2 summary]
- [Phase 3+ summaries]

Key decisions:
- Merged imports from both branches
- Combined test cases
- Regenerated lock files
- [other significant decisions from plan]

Co-Authored-By: ForgeCode <noreply@forgecode.dev>"

Decision Tracking

When you ask the user to choose between options, track their decision and apply similar reasoning to subsequent conflicts:

Example scenario:

1. First conflict: User chooses Option 1 (prefer current branch's validation logic) 2. Second similar conflict: Apply the same reasoning (prefer current branch's validation approach) 3. Mention: "Resolving by keeping current branch's approach (consistent with your earlier choice)"

Key principles:

• Remember user preferences within the same conflict resolution session
• Apply consistent patterns when conflicts are similar
• Mention the consistency: "Following the same pattern as before..."
• Ask again if a new conflict is sufficiently different from previous ones

Common Patterns Reference

For detailed resolution patterns, read:

• references/patterns.md - Comprehensive examples for all conflict types

Quick pattern lookup:

• Imports: Combine all unique imports, group by module
• Tests: Keep all tests unless identical, merge fixtures
• Generated files: Choose either version, regenerate from source
• Config: Merge all keys, choose newer/safer values for conflicts
• Code: Analyze intent, merge if orthogonal, choose one if conflicting
• Structs: Include all fields from both branches
• Docs: Combine all documentation sections

Special Scenarios

Binary Files in Conflict

Binary files cannot be merged. Choose one version:

git checkout --ours path/to/binary    # keep our version
# or
git checkout --theirs path/to/binary  # keep their version

Mass Rename/Refactoring Conflicts

If one branch renamed/refactored many files while another modified them:

1. Accept the rename/refactoring (structural change) 2. Apply the modifications to the new structure 3. Use backups from handle-deleted-modified.sh to guide the application

Submodule Conflicts

# Check submodule status
git submodule status

# Update to the correct commit
cd path/to/submodule
git checkout <desired-commit>
cd ../..
git add path/to/submodule

Troubleshooting

"Both Added" Conflicts (AA)

Both branches added a new file with the same name but different content:

1. Review both versions 2. If they serve the same purpose, merge their content 3. If they serve different purposes, rename one

Whitespace-Only Conflicts

If conflicts are only whitespace differences:

git merge -Xignore-space-change <branch>

Persistent Conflict Markers

If validation shows conflict markers but you think you resolved them:

1. Search for the exact marker strings: git grep -n "<<<<<<< HEAD" 2. Some markers might be in strings or comments - resolve those too 3. Check for hidden characters or encoding issues

Tests Fail After Resolution

1. Test each branch individually to confirm they pass 2. The failure is likely from interaction between the merged changes 3. Debug the interaction issue, not the individual changes 4. Update code to make both changes work together

Quick Reference Card

Remember:

• Always provide a one-line explanation for each conflict resolution
• When unclear, present numbered options to the user
• Track user decisions and apply consistently to similar conflicts
• The goal is to preserve the intent and functionality of both branches while creating a cohesive merged result

Conflict Resolution Patterns

This document provides detailed patterns for resolving specific types of conflicts.

Important: For each conflict you resolve, provide a one-line explanation of your resolution strategy. When the correct resolution isn't clear from the diff, present numbered options to the user.

Import Conflicts

When both branches modify import statements, merge both sets of imports:

Pattern: Combine and Deduplicate

<<<<<<< HEAD
import { foo, bar } from './module';
import { baz } from './other';
=======
import { foo, qux } from './module';
import { newThing } from './another';
>>>>>>> branch

Resolution: Merge all unique imports, group by module:

import { foo, bar, qux } from './module';
import { baz } from './other';
import { newThing } from './another';

Rust Imports

<<<<<<< HEAD
use std::collections::HashMap;
use crate::domain::User;
=======
use std::collections::HashSet;
use crate::domain::Account;
>>>>>>> branch

Resolution:

use std::collections::{HashMap, HashSet};
use crate::domain::{Account, User};

Key principles:

• Combine all unique imports
• Remove duplicates
• Follow language-specific style (group by module, alphabetize)
• Preserve any re-exports or aliases from both sides

One-line explanation example: "Merging imports by combining unique imports from both branches and grouping by module."

Test Conflicts

Tests should almost always include both changes, as tests are additive.

Pattern: Merge Test Cases

<<<<<<< HEAD
#[test]
fn test_user_creation() { ... }

#[test]
fn test_user_validation() { ... }
=======
#[test]
fn test_user_creation() { ... }

#[test]
fn test_user_deletion() { ... }
>>>>>>> branch

Resolution: Include all tests (assuming test_user_creation is identical):

#[test]
fn test_user_creation() { ... }

#[test]
fn test_user_validation() { ... }

#[test]
fn test_user_deletion() { ... }

Test Setup/Fixtures Conflicts

When both branches modify test fixtures, merge the changes:

<<<<<<< HEAD
fn setup() -> TestContext {
    TestContext {
        user: create_test_user(),
        admin: create_admin(),
    }
}
=======
fn setup() -> TestContext {
    TestContext {
        user: create_test_user(),
        database: init_test_db(),
    }
}
>>>>>>> branch

Resolution:

fn setup() -> TestContext {
    TestContext {
        user: create_test_user(),
        admin: create_admin(),
        database: init_test_db(),
    }
}

Key principles:

• Keep all test cases unless they test the exact same thing
• Merge test fixtures and setup functions
• If test names conflict but test different things, rename one
• Preserve all assertions from both sides

One-line explanation example: "Including all test cases from both branches and merging test fixtures."

Lock File Conflicts

Lock files (Cargo.lock, package-lock.json, yarn.lock, etc.) should be regenerated rather than manually resolved.

Pattern: Regenerate Lock File

# For Cargo.lock
git checkout --theirs Cargo.lock  # or --ours, either works
cargo update  # or cargo build

# For package-lock.json
git checkout --theirs package-lock.json
npm install

# For yarn.lock
git checkout --theirs yarn.lock
yarn install

# For Gemfile.lock
git checkout --theirs Gemfile.lock
bundle install

# For poetry.lock
git checkout --theirs poetry.lock
poetry lock --no-update

Key principles:

• Always regenerate, never manually merge
• Choose either version (--ours or --theirs), doesn't matter
• Run the package manager's update/install command
• The result will include dependencies from both branches

One-line explanation example: "Regenerating lock file with package manager to include dependencies from both branches."

Configuration File Conflicts

Configuration files often need careful merging of both changes.

Pattern: Merge Configuration Values

<<<<<<< HEAD
server:
  port: 8080
  timeout: 30
  max_connections: 100
=======
server:
  port: 8080
  timeout: 60
  enable_https: true
>>>>>>> branch

Resolution:

server:
  port: 8080
  timeout: 60  # Prefer the newer/safer value
  max_connections: 100
  enable_https: true

Key principles:

• Include all configuration keys from both sides
• When same key has different values, choose based on:
• Newer value (if timestamp available)
• Safer/more conservative value
• Production-ready value
• Document the choice in commit message

One-line explanation example: "Merging all config keys and choosing incoming value for 'timeout' as it's more recent."

When to ask the user: If conflicting values have significant implications (e.g., security settings, API endpoints), present options:

Config conflict in config.yaml for key 'timeout':

**Option 1**: Keep current value (30 seconds)
**Option 2**: Keep incoming value (60 seconds)
**Option 3**: Provide a different value

Please select an option.

Code Logic Conflicts

When both branches modify the same function, carefully analyze the intent.

Pattern: Sequential Changes

If changes are independent and can coexist:

<<<<<<< HEAD
fn process(data: &str) -> Result<String> {
    let cleaned = data.trim();
    validate(cleaned)?;
    Ok(cleaned.to_uppercase())
}
=======
fn process(data: &str) -> Result<String> {
    let cleaned = data.trim();
    if cleaned.is_empty() {
        return Err(Error::EmptyInput);
    }
    Ok(cleaned.to_uppercase())
}
>>>>>>> branch

Resolution: Combine both validations:

fn process(data: &str) -> Result<String> {
    let cleaned = data.trim();
    if cleaned.is_empty() {
        return Err(Error::EmptyInput);
    }
    validate(cleaned)?;
    Ok(cleaned.to_uppercase())
}

One-line explanation: "Merging both validations as they check different conditions (emptiness and validation)."

Pattern: Conflicting Logic

If changes represent different approaches:

<<<<<<< HEAD
fn calculate_price(item: &Item) -> f64 {
    item.base_price * (1.0 + item.tax_rate)
}
=======
fn calculate_price(item: &Item) -> f64 {
    item.base_price + item.tax_amount
}
>>>>>>> branch

Resolution: Analyze which approach is correct:

• Review PR/commit messages for context
• Check which calculation matches business requirements
• Consider running tests with both approaches
• Choose one and document why in commit message

When to ask the user: Present this as options when the correct approach isn't clear:

Code logic conflict in calculate_price function:

<<<<<<< HEAD (Current Branch)
fn calculate_price(item: &Item) -> f64 {
    item.base_price * (1.0 + item.tax_rate)
}
=======
fn calculate_price(item: &Item) -> f64 {
    item.base_price + item.tax_amount
}
>>>>>>> feature-branch (Incoming Branch)

These represent different calculation methods:

**Option 1**: Keep current branch - calculates tax as percentage (base_price * tax_rate)
**Option 2**: Keep incoming branch - uses pre-calculated tax amount (base_price + tax_amount)
**Option 3**: Ask you to clarify the correct business logic

Please select an option.

One-line explanation example: "Choosing current branch approach as it calculates tax dynamically based on rate (per user selection)."

Struct/Type Definition Conflicts

Merge all fields from both branches.

Pattern: Merge Struct Fields

<<<<<<< HEAD
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub created_at: DateTime,
}
=======
pub struct User {
    pub id: i64,
    pub name: String,
    pub role: UserRole,
    pub updated_at: DateTime,
}
>>>>>>> branch

Resolution:

pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
    pub role: UserRole,
    pub created_at: DateTime,
    pub updated_at: DateTime,
}

Key principles:

• Include all fields from both sides
• If field types conflict, analyze which is more appropriate
• Update all usages of the struct accordingly
• Fix compilation errors after merging

One-line explanation example: "Including all fields from both branches in User struct."

When to ask the user: If the same field has different types:

Struct conflict - field 'role' has different types:

**Option 1**: Keep current type (role: String)
**Option 2**: Keep incoming type (role: UserRole enum)
**Option 3**: Provide more context

Please select an option.

Documentation Conflicts

Merge all documentation improvements.

Pattern: Combine Documentation

<<<<<<< HEAD
/// Processes user input and returns validated data.
/// 
/// # Arguments
/// * `input` - The raw user input
=======
/// Processes user input and returns validated data.
/// 
/// # Errors
/// Returns `Error::InvalidInput` if validation fails
>>>>>>> branch

Resolution:

/// Processes user input and returns validated data.
/// 
/// # Arguments
/// * `input` - The raw user input
/// 
/// # Errors
/// Returns `Error::InvalidInput` if validation fails

Key principles:

• Preserve all documentation sections
• If descriptions conflict, choose the more accurate/detailed one
• Keep all examples from both sides
• Maintain consistent formatting

One-line explanation example: "Combining all documentation sections from both branches."

Deleted File Special Cases

Pattern: File Renamed/Moved

If file was deleted on one branch but modified on another, and there's a similar new file:

1. Check if file was renamed: git log --follow --diff-filter=R -- <file> 2. Apply modifications to the new location 3. Remove the old file

Pattern: File Legitimately Deleted

If file deletion was intentional (feature removed, refactored):

1. Review the modifications from the other branch 2. Determine if any changes are still relevant 3. If yes, apply to the appropriate new location 4. If no, accept the deletion

Pattern: Accidental Deletion

If file should not have been deleted:

1. Restore the file from the branch that kept it 2. Apply any additional modifications 3. Verify tests pass

Sample Merge Resolution Plan

This file provides a complete example of a merge resolution plan for a typical conflict scenario.

Merge Resolution Plan

Conflict Summary

• Total conflicted files: 5
• Deleted-modified conflicts: 1
• Generated files: 1
• Regular conflicts: 3

Resolution Strategy by File

1. Cargo.lock

Conflict Type: generated Strategy: Regenerate from Cargo.toml after merge Rationale: Lock files should never be manually merged; regeneration ensures all dependencies are correctly resolved Risk: Low - Standard procedure for lock files Action Items:

• [ ] Choose either version temporarily
• [ ] Run cargo update to regenerate
• [ ] Stage the regenerated file

2. src/utils/helpers.rs (deleted in incoming, modified in current)

Conflict Type: deleted-modified Strategy: Backup modifications and apply to new location if applicable Rationale: File may have been moved/renamed; need to preserve modifications Risk: Medium - Requires analysis of where changes should go Action Items:

• [ ] Run handle-deleted-modified script to create backup
• [ ] Review analysis report for potential relocation targets
• [ ] Apply modifications to new location if found

3. src/lib.rs

Conflict Type: imports Strategy: Merge all unique imports from both branches Rationale: Both branches likely added new dependencies; combining ensures all code works Risk: Low - Standard import merge pattern Action Items:

• [ ] Extract imports from both sides
• [ ] Deduplicate and sort by module
• [ ] Verify no unused imports

4. tests/integration_test.rs

Conflict Type: tests Strategy: Include all test cases from both branches Rationale: Both branches added new test coverage; all tests should be preserved Risk: Low - Tests are additive Action Items:

• [ ] Merge test functions from both branches
• [ ] Combine test fixtures if needed
• [ ] Ensure no duplicate test names

5. src/config.rs

Conflict Type: code logic Strategy: Need user input - both branches modify validation logic differently Rationale: Cannot determine correct business logic from code alone Risk: High - Affects core validation behavior Action Items:

• [ ] Present both approaches to user
• [ ] Get user decision on which validation logic to use
• [ ] Implement chosen approach

Execution Order

1. Phase 1: Deleted-Modified Files - Handle helpers.rs backup and analysis 2. Phase 2: Generated Files - Regenerate Cargo.lock 3. Phase 3: Low-Risk Merges - Merge imports in lib.rs and tests in integration_test.rs 4. Phase 4: High-Risk Merges - Resolve config.rs after user input 5. Phase 5: Validation - Compile, test, verify

Questions/Decisions Needed

• [ ] src/config.rs: Validation logic conflict - which approach should we use?
• Current branch: Validates using regex patterns
• Incoming branch: Validates using a validation library
• Options: (1) Keep current, (2) Keep incoming, (3) Use both with feature flag

Validation Steps

• [ ] Run conflict validation script
• [ ] Compile with cargo check
• [ ] Run full test suite with cargo test
• [ ] Manual verification of config.rs changes