mergetool Git Command Guide

The git mergetool command runs one of several merge utilities to resolve merge conflicts interactively. It is typically run after git merge when conflicts occur, providing a visual interface for comparing and resolving differences between conflicting file versions.

git mergetool Syntax:

git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]

Tool Selection Options:

Option	Description
-t <tool>, --tool=<tool>	Use specified merge resolution program
--tool-help	Show available merge tools

User Interaction Options:

Option	Description
-y, --no-prompt	Don’t prompt before each file
--prompt	Prompt before each file (default)

Parameters:

Parameter	Description
<file>...	Specific files to resolve conflicts in

Supported Merge Tools:

Built-in Tools:

Tool	Description	Platform
vimdiff	Vim with diff highlighting	Unix/Linux
vimdiff2	Vim with 2-way diff	Unix/Linux
vimdiff3	Vim with 3-way diff	Unix/Linux
gvimdiff	GUI Vim diff	Unix/Linux with GUI
gvimdiff2	GUI Vim 2-way diff	Unix/Linux with GUI
gvimdiff3	GUI Vim 3-way diff	Unix/Linux with GUI

External Tools:

Tool	Description	Platform
kdiff3	Advanced 3-way merge tool	Cross-platform
meld	Visual diff and merge tool	Cross-platform
emerge	Emacs merge tool	Unix/Linux
tortoisemerge	TortoiseSVN merge tool	Windows
diffuse	Simple diff viewer	Cross-platform
ecmerge	ECMerge tool	Cross-platform
p4merge	Perforce merge tool	Cross-platform
araxis	Araxis merge tool	Windows/macOS
bc	Beyond Compare	Windows
codecompare	Devart Code Compare	Windows
deltawalker	DeltaWalker	macOS
winmerge	WinMerge	Windows
xxdiff	Visual diff tool	Unix/Linux

Basic Usage Examples:

Launch Mergetool for All Conflicts:

# Launch mergetool for all conflicted files
git mergetool

# Don't prompt before each file
git mergetool -y

# Use specific merge tool
git mergetool --tool=kdiff3

# Show available tools
git mergetool --tool-help

Process Specific Files:

# Resolve conflicts in specific files
git mergetool conflicted-file.txt another-conflict.c

# Process all conflicts in directory
git mergetool src/

# Process files matching pattern
git mergetool *.js

Tool Configuration:

# Configure default merge tool
git config merge.tool vimdiff

# Configure tool with custom path
git config mergetool.kdiff3.path /usr/local/bin/kdiff3

# Configure tool options
git config mergetool.meld.cmd "meld \$LOCAL \$REMOTE \$BASE \$MERGED"

Advanced Mergetool Configuration:

Custom Tool Setup:

# Configure VS Code as merge tool
git config merge.tool vscode
git config mergetool.vscode.cmd "code --wait --merge \$REMOTE \$LOCAL \$BASE \$MERGED"

# Configure IntelliJ IDEA
git config merge.tool intellij
git config mergetool.intellij.cmd "/Applications/IntelliJ\ IDEA.app/Contents/bin/idea merge \$LOCAL \$REMOTE \$BASE \$MERGED"

# Configure Sublime Text
git config merge.tool sublimemerge
git config mergetool.sublimemerge.cmd "subl --wait --new-window \$MERGED"
git config mergetool.sublimemerge.trustExitCode true

Platform-Specific Configuration:

# Windows configuration
git config merge.tool winmerge
git config mergetool.winmerge.path "C:/Program Files/WinMerge/WinMergeU.exe"
git config mergetool.winmerge.cmd "\"C:/Program Files/WinMerge/WinMergeU.exe\" -u -e \$MERGED"
git config mergetool.winmerge.trustExitCode true

# macOS configuration
git config merge.tool diffmerge
git config mergetool.diffmerge.path "/Applications/DiffMerge.app/Contents/MacOS/DiffMerge"
git config mergetool.diffmerge.cmd "/Applications/DiffMerge.app/Contents/MacOS/DiffMerge --merge --result=\$MERGED \$LOCAL \$BASE \$REMOTE"

Advanced Tool Configuration:

# Configure tool with arguments
git config merge.tool kdiff3
git config mergetool.kdiff3.path /usr/bin/kdiff3
git config mergetool.kdiff3.cmd "kdiff3 --auto --L1 \"\$MERGED (Base)\" --L2 \"\$MERGED (Local)\" --L3 \"\$MERGED (Remote)\" -o \$MERGED \$BASE \$LOCAL \$REMOTE"
git config mergetool.kdiff3.trustExitCode false

# Configure Meld with custom options
git config merge.tool meld
git config mergetool.meld.cmd "meld --diff \$LOCAL \$BASE \$REMOTE --output \$MERGED"
git config mergetool.meld.trustExitCode true

Integration with Development Workflows:

Standard Conflict Resolution Workflow:

#!/bin/bash
# Complete conflict resolution workflow

resolve_merge_conflicts() {
    echo "=== Merge Conflict Resolution ==="

    # Check for conflicts
    if ! git ls-files -u | grep -q .; then
        echo "No merge conflicts detected"
        return 0
    fi

    echo "Found $(git ls-files -u | wc -l) conflicted entries"

    # Launch mergetool for all conflicts
    if git mergetool -y; then
        echo "✓ All conflicts resolved"

        # Check if all conflicts are resolved
        if git ls-files -u | grep -q .; then
            echo "✗ Some conflicts remain - manual resolution needed"
            return 1
        else
            echo "✓ All conflicts resolved successfully"
            return 0
        fi
    else
        echo "✗ Mergetool failed or was cancelled"
        return 1
    fi
}

resolve_merge_conflicts

Interactive Resolution with Backup:

# Interactive conflict resolution with safety
interactive_merge_resolution() {
    local backup_branch="backup-before-resolution-$(date +%Y%m%d-%H%M%S)"

    # Create backup
    git branch "$backup_branch"
    echo "Backup created: $backup_branch"

    # Show conflicted files
    echo "Conflicted files:"
    git ls-files -u | awk '{print $4}' | sort | uniq

    # Launch mergetool interactively
    git mergetool

    # Verify resolution
    if git ls-files -u | grep -q .; then
        echo "Conflicts remain. Options:"
        echo "1. Continue with git mergetool"
        echo "2. Edit files manually and run git add"
        echo "3. Abort with git merge --abort"
        echo "4. Restore from backup: git reset --hard $backup_branch"
        return 1
    else
        echo "✓ All conflicts resolved"
        echo "Clean up backup branch: git branch -D $backup_branch"
        return 0
    fi
}

interactive_merge_resolution

Batch Conflict Processing:

# Process conflicts in organized batches
batch_conflict_resolution() {
    local batch_size="${1:-5}"

    # Get list of conflicted files
    conflicted_files=$(git ls-files -u | awk '{print $4}' | sort | uniq)

    if [ -z "$conflicted_files" ]; then
        echo "No conflicts to resolve"
        return 0
    fi

    echo "Processing $(echo "$conflicted_files" | wc -l) conflicted files in batches of $batch_size"

    # Process in batches
    echo "$conflicted_files" | \
    xargs -n "$batch_size" | \
    while read batch; do
        echo "=== Processing batch: $batch ==="

        for file in $batch; do
            echo "Resolving: $file"
            git mergetool "$file"

            if [ $? -eq 0 ]; then
                echo "✓ $file resolved"
            else
                echo "✗ $file needs manual attention"
            fi
        done

        echo "--- Batch complete ---"
    done

    # Final status check
    remaining=$(git ls-files -u | wc -l)
    if [ "$remaining" -eq 0 ]; then
        echo "✓ All conflicts resolved"
    else
        echo "✗ $remaining conflicts remain"
    fi
}

batch_conflict_resolution 3

Tool-Specific Configuration:

Vimdiff Configuration:

# Configure vimdiff for merge
git config merge.tool vimdiff
git config mergetool.vimdiff.path vim
git config mergetool.vimdiff.cmd "vim -f -d -c 'wincmd J' \$MERGED \$LOCAL \$BASE \$REMOTE"

# Advanced vimdiff setup
git config mergetool.vimdiff.layout "LOCAL,REMOTE"
git config mergetool.vimdiff.trustExitCode true

KDiff3 Configuration:

# Configure KDiff3 for advanced merging
git config merge.tool kdiff3
git config mergetool.kdiff3.path kdiff3
git config mergetool.kdiff3.cmd "kdiff3 --auto --L1 \"\$MERGED (Base)\" --L2 \"\$MERGED (Local)\" --L3 \"\$MERGED (Remote)\" -o \$MERGED \$BASE \$LOCAL \$REMOTE"
git config mergetool.kdiff3.trustExitCode false

# Enable auto-save and backup
git config mergetool.kdiff3.keepBackup false
git config mergetool.kdiff3.keepTemporaries false

Meld Configuration:

# Configure Meld for intuitive merging
git config merge.tool meld
git config mergetool.meld.path meld
git config mergetool.meld.cmd "meld \$LOCAL \$BASE \$REMOTE --output \$MERGED"
git config mergetool.meld.trustExitCode true

# Custom Meld layout
git config mergetool.meld.layout "LOCAL,BASE,REMOTE"

Troubleshooting Common Issues:

Tool Not Found:

# Check if tool is installed
which kdiff3 meld vimdiff

# Check tool configuration
git config --list | grep mergetool

# Test tool manually
kdiff3 --version
meld --version

Tool Launch Failures:

# Check tool permissions
ls -la /usr/bin/kdiff3
ls -la /usr/bin/meld

# Test tool with sample files
echo "test" > test1.txt
echo "test2" > test2.txt
kdiff3 test1.txt test2.txt

# Check display environment
echo $DISPLAY  # For GUI tools

File Permission Issues:

# Check file permissions
git ls-files --stage conflicted-file.txt

# Fix permissions
chmod 644 conflicted-file.txt

# Handle read-only files
chmod u+w conflicted-file.txt

Large File Issues:

# Check file sizes
du -h conflicted-file.txt

# Configure tool for large files
git config mergetool.largefiletool vimdiff

# Split large files if needed
split -l 1000 large-file.txt part-
git mergetool part-aa
cat part-a* > resolved-large-file.txt

Caution

git mergetool modifies files in place. Always backup important files before using. Some tools may not handle binary files or very large files well.

Real-World Usage Examples:

Team Development Workflow:

#!/bin/bash
# Team conflict resolution workflow

team_conflict_resolution() {
    local feature_branch="$1"
    local target_branch="${2:-main}"

    echo "=== Team Conflict Resolution ==="
    echo "Feature: $feature_branch"
    echo "Target: $target_branch"

    # Ensure we're on target branch
    git checkout "$target_branch"
    git pull origin "$target_branch"

    # Start merge
    if git merge "$feature_branch"; then
        echo "✓ Clean merge - no conflicts"
        return 0
    fi

    echo "Conflicts detected - launching resolution tools"

    # Show conflicted files
    echo "Conflicted files:"
    git ls-files -u | awk '{print $4}' | sort | uniq

    # Launch mergetool for all conflicts
    if git mergetool -y; then
        echo "✓ All conflicts resolved"

        # Verify resolution
        if git ls-files -u | grep -q .; then
            echo "✗ Some conflicts remain"
            return 1
        else
            # Complete merge
            git commit -m "Merge $feature_branch with conflict resolution"
            git push origin "$target_branch"
            echo "✓ Merge completed and pushed"
        fi
    else
        echo "✗ Mergetool failed"
        echo "Manual resolution needed"
        return 1
    fi
}

# Usage
team_conflict_resolution "feature/user-authentication" "develop"

Quality Assurance Integration:

# QA merge validation with mergetool
qa_merge_validation() {
    local merge_commit="$1"

    echo "=== QA Merge Validation ==="

    # Check for unresolved conflicts
    if git ls-files -u | grep -q .; then
        echo "✗ Merge has unresolved conflicts"
        echo "Run: git mergetool"
        return 1
    fi

    # Validate merge quality
    echo "Validating merge quality..."

    # Check for conflict markers in committed files
    if git show "$merge_commit" | grep -q "^<<<<<<<\|^=======\|^>>>>>>>"; then
        echo "✗ Found conflict markers in merge commit"
        return 1
    fi

    # Validate file integrity
    git show "$merge_commit" --name-only | \
    while read file; do
        if [ -f "$file" ]; then
            # Check for syntax errors in code files
            case "${file##*.}" in
                py) python -m py_compile "$file" 2>/dev/null && echo "✓ $file syntax OK" ;;
                js) node -c "$file" 2>/dev/null && echo "✓ $file syntax OK" ;;
                *) echo "✓ $file present" ;;
            esac
        fi
    done

    echo "✓ Merge validation passed"
    return 0
}

# Use in QA process
qa_merge_validation "HEAD"

Enterprise Conflict Management:

#!/bin/bash
# Enterprise conflict resolution with tracking

enterprise_conflict_resolution() {
    local ticket_id="$1"
    local resolution_strategy="${2:-interactive}"

    echo "=== Enterprise Conflict Resolution ==="
    echo "Ticket: $ticket_id"
    echo "Strategy: $resolution_strategy"
    echo "Timestamp: $(date)"

    # Pre-resolution validation
    conflicted_files=$(git ls-files -u | awk '{print $4}' | sort | uniq)
    if [ -z "$conflicted_files" ]; then
        echo "No conflicts detected"
        return 0
    fi

    echo "Found $(echo "$conflicted_files" | wc -l) conflicted files"

    # Create resolution record
    cat > "conflict-resolution-$ticket_id.log" << EOF
Conflict Resolution Record
Ticket: $ticket_id
Date: $(date)
Strategy: $resolution_strategy
User: $(git config user.name) <$(git config user.email)>

Conflicted Files:
$(echo "$conflicted_files" | sed 's/^/  /')

EOF

    # Resolution strategy selection
    case "$resolution_strategy" in
        "automatic")
            echo "Attempting automatic resolution..."
            if git merge-index git-merge-one-file -a; then
                echo "✓ Automatic resolution successful"
            else
                echo "✗ Automatic resolution failed - falling back to interactive"
                resolution_strategy="interactive"
            fi
            ;;
        "interactive")
            echo "Launching interactive resolution..."
            git mergetool -y
            ;;
        "guided")
            echo "Launching guided resolution..."
            git mergetool  # With prompts
            ;;
    esac

    # Post-resolution validation
    remaining_conflicts=$(git ls-files -u | wc -l)
    if [ "$remaining_conflicts" -eq 0 ]; then
        echo "✓ All conflicts resolved"

        # Update resolution record
        cat >> "conflict-resolution-$ticket_id.log" << EOF

Resolution Summary:
Status: SUCCESS
Resolved files: $(echo "$conflicted_files" | wc -l)
Strategy used: $resolution_strategy
Resolution time: $(($(date +%s) - $(date -r "conflict-resolution-$ticket_id.log" +%s))) seconds

EOF

        echo "Resolution record: conflict-resolution-$ticket_id.log"
        return 0
    else
        echo "✗ $remaining_conflicts conflicts remain"

        # Update resolution record with failure
        cat >> "conflict-resolution-$ticket_id.log" << EOF

Resolution Summary:
Status: PARTIAL
Remaining conflicts: $remaining_conflicts
Manual intervention required

EOF

        echo "Resolution record: conflict-resolution-$ticket_id.log"
        return 1
    fi
}

# Usage
enterprise_conflict_resolution "PROJ-1234" "interactive"

Tip

Configure your preferred merge tool with git config merge.tool . Use git mergetool —tool-help to see available tools. Test tool configuration before production use.

What’s the difference between git mergetool and git merge —no-commit?

git mergetool resolves conflicts interactively after merge fails; git merge —no-commit stops before committing to allow manual conflict resolution.

How do I configure custom merge tools?

Use git config merge.tool and git config mergetool..cmd to set up custom tools with appropriate command-line arguments.

Can mergetool work with binary files?

Most visual merge tools are designed for text files. For binary files, use git checkout —ours or git checkout —theirs to choose one version.

What’s the relationship between mergetool and merge drivers?

Merge drivers handle automatic merging; mergetool provides interactive resolution when automatic merging fails or conflicts occur.

How do I handle mergetool in headless environments?

Use text-based tools like vimdiff, or configure tools that don’t require GUI. Some tools support —no-gui options.

Can mergetool work with Git LFS files?

Yes, works normally with LFS pointer files. LFS handles the large file content separately from the Git merge process.

What’s the performance impact of mergetool?

Depends on tool and file size. Visual tools may be slower for very large files. Use —no-prompt for batch processing.

How do I handle mergetool timeouts?

Configure tool timeouts in git config or use external timeout commands. Some tools have built-in timeout settings.

Can mergetool work in bare repositories?

No, requires working directory with files. Use in non-bare repositories or create temporary working directory for bare repo merges.

What’s the difference between vimdiff and vimdiff3?

vimdiff shows 2-way diff; vimdiff3 shows 3-way diff with base, local, and remote versions for better conflict understanding.

How do I integrate mergetool with IDEs?

Most IDEs provide Git integration with mergetool support. Configure IDE as merge tool or use IDE’s built-in merge resolution.

Can mergetool handle multiple files simultaneously?

Most tools handle one file at a time. Use git mergetool -y for batch processing or process files individually.

What’s the relationship between mergetool and git rerere?

git rerere records conflict resolutions for reuse; mergetool provides the interface for initial resolution that rerere can learn from.

How do I handle mergetool in CI/CD pipelines?

Use text-based tools or automated resolution. Interactive tools don’t work in headless CI environments.

Can mergetool work with custom merge strategies?

Yes, mergetool works with any merge strategy. Configure appropriate tools for different file types and merge scenarios.

Applications of the git mergetool command

1. Interactive Conflict Resolution: Provide visual interface for resolving merge conflicts with three-way diff visualization
2. Team Collaboration: Enable team members to resolve conflicts using familiar tools and interfaces
3. Code Review Integration: Support conflict resolution during code review and merge request processes
4. Development Workflow Enhancement: Integrate conflict resolution into development environments and IDEs
5. Quality Assurance: Validate merge quality and ensure proper conflict resolution in QA processes
6. Enterprise Merge Management: Support complex merge requirements with tracked and audited conflict resolution