Chapter 3.6 — Binary File Conflicts☕ 12 min read

Binary File Conflicts

Binary conflict matlab choose one: --ours ya --theirs. Adha nahi hoga. Aur dist/ build/ jaisi files KABHI commit mat karo, .gitignore mein daalo!

01Why Git Can't Merge Binary Files

Text files are Git's best friend. Git can compare them line by line, understand which lines changed, and merge different sections from two branches automatically. When two developers edit different parts of the same text file, Git combines both changes seamlessly.

Binary files — images (PNG, JPG), PDFs, Word documents (.docx), ZIP archives, compiled executables — are completely different. Git cannot understand their internal structure. A PNG file is not lines of text; it is encoded pixel data. A .docx file is actually a ZIP of XML files.

When two branches modify the same binary file, Git can only say "CONFLICT" — it cannot show you the differences the way it does for text files. There is no way to "combine" two images or two PDFs in Git.

You must choose one version entirely: keep yours, or keep theirs. Half and half is not possible for binary files.

# Binary file conflict
git merge feature
# CONFLICT (content): Merge conflict in logo.png

# Git can't show you the diff like text files
git diff logo.png
# Binary files /dev/null and logo.png differ
# Not helpful! You can't see what changed.

# You must choose one version:
git checkout --ours logo.png     # keep your version
# OR
git checkout --theirs logo.png   # keep their version

Binary files are opaque to Git. It does not matter if the file is a photo, a PDF, or a compiled binary — Git sees them all as blobs of bytes. It cannot parse, compare, or merge their contents. The only resolution is choosing one complete version. This is why preventing binary conflicts through .gitignore and .gitattributes is so important.

02Resolving Binary Conflicts: Choose One

The resolution process for binary conflicts is simpler than text conflicts, but more dangerous because you cannot see what you are choosing.

git checkout --ours <file> — keep YOUR version (the one on the current branch). This keeps the file as it exists in HEAD.

git checkout --theirs <file> — keep the INCOMING version (the one from the branch you are merging). This replaces the file with the incoming branch's version.

After choosing, you must run git add <file> and git commit to complete the merge. Git will not auto-commit a binary resolution.

CRITICAL: Open the file after resolving to verify you chose the right version! For images, visually inspect them. For PDFs, open and read them. Do not guess — you cannot undo easily once pushed.

# Binary conflict resolution steps:
# 1. See which files are conflicted
git status
# Unmerged paths: both modified: logo.png

# 2. Choose a version
git checkout --theirs logo.png    # keep feature's version

# 3. Stage the resolution
git add logo.png

# 4. Commit
git commit -m "merge: keep updated logo from feature"

# To keep YOUR version:
git checkout --ours logo.png
git add logo.png
git commit -m "merge: keep our logo design"

💡 Pro Tip: After resolving a binary conflict, always open the file and verify it is the version you intended. Unlike text conflicts where you can read the diff in the terminal, binary conflicts are invisible. The wrong logo or wrong PDF in production is an embarrassing mistake that is easy to prevent with a 5-second visual check.

03Configuring Merge Strategy with .gitattributes

You can tell Git to automatically resolve binary conflicts using .gitattributes. This file defines how Git handles different file types during merges.

*.png merge=ours — always keep our version for PNG conflicts. No manual resolution needed.

*.pdf binary — mark the file as binary so Git does not try to diff or merge it. This prevents corrupt merge attempts.

The merge=ours strategy requires a custom merge driver configured in .git/config. A simpler built-in approach: use union or just mark files as binary.

.gitattributes is committed to the repo, so the strategy applies to everyone on the team. One person sets it up, everyone benefits.

# .gitattributes - automatic binary conflict resolution

# Always keep our version for design assets
echo "*.png merge=ours" >> .gitattributes
echo "*.jpg merge=ours" >> .gitattributes
echo "*.psd merge=ours" >> .gitattributes

# Mark files as binary (prevents Git from trying to diff)
echo "*.zip binary" >> .gitattributes
echo "*.exe binary" >> .gitattributes
echo "*.pdf binary" >> .gitattributes

# Commit .gitattributes
git add .gitattributes
git commit -m "chore: add gitattributes for binary files"

# With merge=ours configured, future conflicts on PNGs auto-resolve!

To use merge=ours, you also need to configure the merge driver. Run git config --global merge.ours.driver true. This tells Git that the "ours" merge strategy simply means "keep our version." Without this config, merge=ours in .gitattributes has no effect. Team members must each configure this driver.

04The Real Problem: Committing Generated Files

The most common source of binary conflicts is not images or PDFs — it is generated files: dist/, build/, compiled .js from .ts, .pyc files, minified assets.

These files are GENERATED from source code. They should NOT be committed. Every build creates a new version, and different developers' builds produce slightly different outputs — guaranteed conflicts.

If you commit dist/, every pull request that includes a build step will conflict with every other pull request that also builds. This is madness.

The solution is simple: add generated files to .gitignore and regenerate them on each checkout or in CI/CD. Only commit source files (.ts, .scss, .py). Build outputs should be gitignored.

# NEVER commit generated files
echo "dist/" >> .gitignore
echo "build/" >> .gitignore
echo "*.pyc" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.min.js" >> .gitignore
echo "*.min.css" >> .gitignore

# If already tracked, untrack them:
git rm -r --cached dist/
git rm --cached app.min.js
git commit -m "chore: stop tracking generated files"

# Instead, generate in CI/CD pipeline
# .github/workflows/build.yml
# - run: npm run build
# This ensures consistent builds without conflicts

💡 Exception: Some deployment workflows (like GitHub Pages from a gh-pages branch) require committed build artifacts. In these cases, use a dedicated branch for build output, never mix source and build in the same branch. Better yet, use CI/CD to build and deploy directly, eliminating the need to commit generated files at all.

05Design Asset Workflow for Teams

Design files (Figma, PSD, Sketch) should ideally be stored in a design tool like Figma, not in Git. But sometimes you need to version them.

If you must store design assets in Git, use Git LFS (Large File Storage). Git LFS stores the actual binary content on a separate server, keeping your repository small and reducing conflicts.

Without LFS, every PSD file bloats the repository permanently. Git stores full snapshots — a 50MB PSD changed 10 times means 500MB in your repository, even after deleting the file.

Use a naming convention: logo-v2.png, hero-banner-final.png. Communicate with designers before updating shared assets. Consider a separate branch or repo for design assets that change frequently.

# Git LFS for design assets
git lfs install
git lfs track "*.psd"
git lfs track "*.sketch"
git lfs track "*.fig"

# .gitattributes is auto-updated by LFS
cat .gitattributes
# *.psd filter=lfs diff=lfs merge=lfs -text
# *.sketch filter=lfs diff=lfs merge=lfs -text

# Now commit and push as normal
git add logo.psd
git commit -m "design: add logo from design team"

# View LFS tracked files
git lfs ls-files
# abc1234 - logo.psd

Git LFS replaces large files with small pointer files in your repository. The actual binary is stored on an LFS server. When you clone, LFS downloads only the version you need. This keeps your repo fast and small. GitHub offers 1GB free LFS storage. GitLab and Bitbucket also support LFS. If your team works with large binary assets, LFS is not optional — it is essential infrastructure.

Lo kar liya — Key Points:

✅ Git cannot merge binary files (images, PDFs, compiled files) because it can't understand their internal structure
✅ Resolve binary conflicts by choosing one version: git checkout --ours <file> or git checkout --theirs <file>
✅ Use .gitattributes to configure automatic resolution strategies for binary file types (e.g., *.png merge=ours)
✅ NEVER commit generated files (dist/, build/, *.min.js) — add them to .gitignore and regenerate via CI
✅ For design assets that must be versioned, use Git LFS to store them separately and reduce conflicts
✅ Always visually verify binary files after resolving conflicts — you can't diff them in the terminal

Previous3.5 — Prevention Strategies 📋 All Chapters Next Chapter3.7 — package-lock.json Conflicts →