# warning: Cannot merge binary files: image.png (HEAD vs. origin/main)

- **ID:** `git/conflict-in-binary-file`
- **Domain:** git
- **Category:** runtime_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

Git cannot automatically merge binary files (e.g., images, PDFs) because they have no text-based diff, leading to a conflict that requires manual resolution.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| git 2.26.0 | active | — | — |
| git 2.33.0 | active | — | — |
| git 2.38.0 | active | — | — |

## Workarounds

1. **Choose one version explicitly: git checkout --ours image.png (keep HEAD version) or git checkout --theirs image.png (keep incoming version), then git add image.png** (85% success)
   ```
   Choose one version explicitly: git checkout --ours image.png (keep HEAD version) or git checkout --theirs image.png (keep incoming version), then git add image.png
   ```
2. **If both versions are needed, manually copy the correct version from a backup or regenerate the file, then git add image.png** (75% success)
   ```
   If both versions are needed, manually copy the correct version from a backup or regenerate the file, then git add image.png
   ```
3. **Use a dedicated binary merge tool like 'git lfs' or 'git-annex' for large binary files to avoid conflicts in the future.** (70% success)
   ```
   Use a dedicated binary merge tool like 'git lfs' or 'git-annex' for large binary files to avoid conflicts in the future.
   ```

## Dead Ends

- **** — Binary files contain non-text data; editing them as text corrupts the file. (95% fail)
- **** — Most merge tools cannot display a meaningful diff for binaries; the tool may fail or show nothing useful. (80% fail)
- **** — Git still marks the file as conflicted; the merge cannot complete until the conflict is resolved. (100% fail)