Unity Git Configuration

.gitattributes for Unity: Smart Merge, Git LFS, and File Locking

A Unity .gitattributes file should keep text-serialized Unity assets available to diff and merge tools, route genuinely large binary formats through Git LFS, normalize line endings where needed, and mark only deliberately lockable assets. One wildcard should not try to solve all four jobs.

A practical Unity .gitattributes starter

# Unity text assets: keep readable and route to a Unity-aware driver
*.unity  text eol=lf merge=unityyamlmerge
*.prefab text eol=lf merge=unityyamlmerge
*.asset  text eol=lf merge=unityyamlmerge
*.mat    text eol=lf merge=unityyamlmerge
*.meta   text eol=lf

# Large binary source assets
*.psd  filter=lfs diff=lfs merge=lfs -text lockable
*.fbx  filter=lfs diff=lfs merge=lfs -text lockable
*.blend filter=lfs diff=lfs merge=lfs -text lockable
*.wav  filter=lfs diff=lfs merge=lfs -text lockable
*.mp4  filter=lfs diff=lfs merge=lfs -text lockable

This is a starting point, not a universal list. Add formats based on actual repository size, binary behavior, hosting limits, and team ownership. Keep the file tracked in the repository so every clone gets the same path policy.

How the merge attribute works

A rule such as *.unity merge=unityyamlmerge selects a custom low-level merge driver named unityyamlmerge. The driver's executable and arguments live in Git config, not in .gitattributes.

git config merge.unityyamlmerge.name "Unity Smart Merge"
git config merge.unityyamlmerge.driver \
  '"/path/to/UnityYAMLMerge" merge -p %O %B %A %A'

Git replaces %O, %A, and %B with ancestor, current, and other temporary files. Validate argument order against the Unity version installed on each platform. The tracked attribute and local executable config are both required.

The MergeSight setup wizard can alternatively write MergeSight-specific rules and local driver settings. Its transparent Unity Git merge-driver workflow writes the current file only when an auto-safe semantic result is fully ready and returns non-zero for unsafe cases.

How Git LFS attributes change file behavior

filter=lfs diff=lfs merge=lfs -text tells Git to store an LFS pointer in normal Git history and place the binary object in LFS storage. This is appropriate for large, non-mergeable formats. It is usually wrong for text-serialized Unity scenes and prefabs because reviewers would see the pointer instead of Unity YAML.

The lockable attribute integrates with Git LFS locking. Use it for formats where concurrent edits cannot be merged. Do not assume that adding lockable alone creates a complete policy: developers still need the Git LFS client, server locking support, and clear lock ownership.

Understand rule order and precedence

Attributes are applied by matching patterns, and later matching lines can change previously assigned values. Avoid broad rules such as Assets/** filter=lfs; they can accidentally convert scripts, meta files, scenes, and prefabs into LFS pointers.

Verify what Git will actually do

git check-attr -a -- Assets/Scenes/World.unity
git check-attr -a -- Assets/Prefabs/Enemy.prefab
git check-attr -a -- Assets/Art/Enemy.psd
git lfs track
git config --get-regexp '^merge\.'

Run these checks on representative paths. If an existing file changes treatment, inspect whether it is already stored under the old rule. Attribute edits are not a substitute for migrating existing Git or LFS history.

Common Unity .gitattributes mistakes

• Tracking every file under Assets/ with LFS.
• Defining a merge attribute without configuring the named Git driver.
• Using a UnityYAMLMerge path tied to one developer's Unity version.
• Marking text scenes as binary and losing useful diff and merge behavior.
• Adding LFS rules after large files are committed and assuming history was migrated.
• Making every Unity asset lockable instead of using a risk-based policy.

FAQ

What should be in .gitattributes for a Unity project?

Keep Unity YAML assets as text with a Unity-aware merge driver, normalize meta files as text, route selected large binary extensions through Git LFS, and mark only intentionally non-mergeable formats lockable.

Should .unity files be tracked by Git LFS?

Usually no. With Force Text enabled, scene files can be diffed and merged. LFS would replace their normal Git content with pointer files and remove that workflow.

Where is a custom Git merge driver configured?

The path pattern and merge driver name go in .gitattributes. The driver command itself is configured in repository or user Git config under merge.<name>.driver.

How do I test Unity .gitattributes rules?

Run git check-attr -a on representative scene, prefab, meta, and binary paths, then inspect git lfs track and the configured merge drivers.

Summary

Keep Unity YAML visible

Scenes, prefabs, selected asset files, materials, and meta files should stay text by default.

Use LFS deliberately

Apply LFS to large binary formats, not the complete Assets tree.

Test effective rules

Use git check-attr and a disposable merge before trusting the configuration.

The best attributes file preserves useful review information while routing only truly binary and non-mergeable content into special handling.

Next step

Decide the binary extension list with Unity Git LFS: Which Assets Should Use It?