How to fix warning: Cannot merge binary files: image.png in Git

GitBEGINNERLOW

This warning occurs when Git cannot automatically merge changes to binary files like images, PDFs, or compiled binaries. Since Git can only insert conflict markers into text files, you must manually choose which version of the binary file to keep using git checkout --ours or --theirs.

What this error means

When you see "warning: Cannot merge binary files", Git is telling you that it has detected conflicting changes to a binary file (such as an image, PDF, video, compiled executable, or any non-text file) and cannot automatically resolve the conflict. Unlike text files where Git can insert conflict markers (<<<<<<, =======, >>>>>>) to show both versions, binary files cannot be meaningfully merged line by line. Git cannot insert conflict markers into a JPEG image or a compiled DLL - the result would be a corrupted, unusable file. Instead of attempting to merge, Git marks the file as conflicted and waits for you to decide which version to keep. You must explicitly choose either your version (from the current branch) or their version (from the branch being merged). There is no automatic "combine both" option for binary files. This commonly occurs with: - Images (PNG, JPG, GIF, SVG) - Documents (PDF, Word, Excel) - Compiled files (DLL, JAR, .o, .pyc) - Archives (ZIP, tar.gz) - Design files (Photoshop, Sketch, Figma exports) - Database files (SQLite, .db)

How to fix "warning: Cannot merge binary files: image.png"

1Identify the conflicted binary files

First, check which binary files are in conflict:

bash

# Show all conflicted files
git status

# You'll see output like:
# Unmerged paths:
#   both modified:   assets/image.png
#   both modified:   docs/report.pdf

# List only conflicted files
git diff --name-only --diff-filter=U

For each binary file listed, you'll need to choose which version to keep.

2Compare the two versions visually (if applicable)

Before choosing a version, you may want to view both files:

bash

# Extract your version (from current branch)
git show :2:assets/image.png > image_ours.png

# Extract their version (from incoming branch)
git show :3:assets/image.png > image_theirs.png

# Now you can open both files and compare them visually

Stage numbers explained:
- :1: - Common ancestor (base version)
- :2: - Ours (current branch / HEAD)
- :3: - Theirs (incoming branch)

For images, open both extracted files in an image viewer. For documents, compare them manually or use specialized diff tools.

3Choose the version to keep

Use git checkout with --ours or --theirs to select which version to keep:

Keep your current branch's version:

bash

git checkout --ours assets/image.png
git add assets/image.png

Keep the incoming branch's version:

bash

git checkout --theirs assets/image.png
git add assets/image.png

Alternative syntax using stage numbers:

bash

# Keep ours (stage 2)
git checkout --ours -- path/to/file.png

# Keep theirs (stage 3)
git checkout --theirs -- path/to/file.png

Important: After checking out your chosen version, you must git add the file to mark the conflict as resolved.

4Replace with an entirely new version (optional)

Sometimes neither version is correct and you need to create a new version:

bash

# Option 1: Replace with a file from your filesystem
cp /path/to/correct/image.png assets/image.png
git add assets/image.png

# Option 2: Replace with a specific version from any commit
git checkout abc1234 -- assets/image.png
git add assets/image.png

# Option 3: Pull from a different branch entirely
git checkout feature-design -- assets/image.png
git add assets/image.png

This is useful when you need to merge the changes manually outside of Git (e.g., in Photoshop) and save the result.

5Resolve all conflicts and complete the merge

After resolving all binary file conflicts, complete the merge:

bash

# Verify all conflicts are resolved
git status
# Should show: "All conflicts fixed but you are still merging"

# Complete the merge
git commit -m "Merge branch 'feature' with resolved binary conflicts"

If there are remaining text file conflicts, resolve those with your editor before committing.

6Use git mergetool for binary files (advanced)

Some specialized tools can help with binary merges:

bash

# Run mergetool for all conflicted files
git mergetool

# If mergetool reports "no files need merging", try:
git mergetool *

Configure a custom binary merge driver:

For specific file types, you can define custom merge behavior in .gitattributes:

bash

# In .gitattributes - mark files as binary (no auto-merge attempt)
*.png binary
*.jpg binary
*.pdf binary

# Or define a custom merge driver
*.png merge=binary

This ensures Git treats these files as binary even if auto-detection fails.

7Abort the merge if needed

If you need to cancel the merge and try a different approach:

bash

# Abort and return to pre-merge state
git merge --abort

# Clean up any extracted comparison files
rm -f image_ours.png image_theirs.png

This is useful when:
- You need to coordinate with the other developer first
- You want to manually create a combined version before merging
- The merge was started by mistake

Advanced notes

### Using Git Attributes for Binary Files

Configure Git to always treat certain files as binary in your .gitattributes:

bash

# Mark specific file types as binary
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.pdf binary
*.doc binary
*.docx binary
*.xls binary
*.xlsx binary
*.zip binary
*.tar.gz binary

### Custom Merge Drivers

You can create custom merge drivers for specific binary formats. For example, using a tool that can diff images:

bash

# In ~/.gitconfig or .git/config
[merge "image"]
    name = Image merge driver
    driver = /path/to/image-merge-script %O %A %B %P

Then in .gitattributes:

bash

*.png merge=image

### Git LFS Considerations

If you're using Git LFS (Large File Storage), binary merge conflicts work slightly differently:

bash

# For LFS files, you may need to:
git lfs fetch --all
git checkout --ours path/to/file.png
git add path/to/file.png

LFS stores the actual binary content separately and Git tracks pointer files, but merge conflicts still require manual resolution.

### Preventing Binary Conflicts

Best practices to avoid binary merge conflicts:

1. Communicate: Let team members know when you're modifying shared assets
2. Lock files: Some Git hosting platforms support file locking for binary files
3. Single ownership: Assign binary assets to specific team members
4. Asset management: Use dedicated asset management systems for design files
5. Don't commit generated files: Add compiled/generated binaries to .gitignore

### Text Files Misidentified as Binary

Sometimes Git misidentifies text files as binary due to:
- Unicode BOM (Byte Order Mark)
- NUL characters in the file
- Mixed line endings

Force Git to treat a file as text:

bash

# In .gitattributes
*.yourextension text

Check if a file contains binary content:

bash

file yourfile.ext
# Or
git diff --stat HEAD~1 yourfile.ext

### Resolving During Rebase

When rebasing with binary conflicts:

bash

# After resolving the binary conflict
git checkout --theirs path/to/binary.png  # or --ours
git add path/to/binary.png
git rebase --continue

### Using External Diff/Merge Tools

Some tools support binary comparison:

- Beyond Compare: Can compare images, PDFs, and many binary formats
- Kaleidoscope (macOS): Image comparison support
- DiffMerge: Limited binary support

Configure in Git:

bash

git config --global diff.tool bc3
git config --global merge.tool bc3

How to fix warning: Cannot merge binary files: image.png in Git

What this error means

Typical symptoms

Common causes

How to fix "warning: Cannot merge binary files: image.png"

Advanced notes

Related errors

Official resources & further reading