Fix: Resource UID Conflict After Git Merge in Godot

If you’ve ever merged a teammate’s branch in a Godot project and been greeted by a wall of conflicts in files you’ve never touched, you’re almost certainly dealing with resource UID conflicts. Godot 4 introduced a UID system to track resources by a stable integer rather than by file path, which is great for renaming files without breaking references—but it creates real headaches when two branches generate different UIDs for the same resource.

Understanding Godot’s Resource UID System

Godot 4 assigns every resource—scenes, scripts, textures, audio files—a unique integer identifier stored in a .uid sidecar file alongside the resource. For example, if you have player.tscn, you’ll also find player.tscn.uid containing a single line like uid://b4k2mxr7c1q6d. These UIDs are then embedded inside .tscn and .tres files wherever one resource references another.

The editor also maintains a uid_cache.bin file inside the .godot directory. This binary cache maps UIDs to file paths for fast lookups at runtime. It’s regenerated automatically when the editor opens the project, so it should never be committed to version control. If you see this file in your repository, add it to .gitignore immediately.

The conflict arises because UID generation is not deterministic across machines or branches. When two developers both add a new resource—or even just open a scene that triggers a UID assignment—Godot will generate different UIDs on each machine. After merging, Git sees two different values for the same .uid file and flags a conflict.

Step-by-Step Conflict Resolution

When you encounter UID conflicts after a merge, follow this process to resolve them cleanly:

First, identify all conflicting files. Run this from your project root:

# List all files with merge conflicts
git diff --name-only --diff-filter=U

# Filter to just UID-related conflicts
git diff --name-only --diff-filter=U | grep -E '\.(uid|tscn|tres)$'

For the .uid files themselves, the safest approach is to accept one side consistently. If you’re merging a feature branch into main, accept the main branch’s UIDs:

# Accept main's version of all .uid files
git checkout --ours -- '*.uid'
git add -- '*.uid'

Alternatively, if the feature branch introduced the new resources, accept theirs:

# Accept the feature branch's UIDs
git checkout --theirs -- '*.uid'
git add -- '*.uid'

For conflicting .tscn and .tres files, you need to ensure the uid:// references inside them match whichever side you chose for the .uid files. Open each conflicting scene file and resolve the UID references to match. In most cases, accepting the same side (--ours or --theirs) for these files works, but if both branches made legitimate scene changes, you may need to manually merge the non-UID portions.

Preventing Future Conflicts with .gitattributes

You can dramatically reduce UID merge pain by adding a custom merge strategy for .uid files. Add this to your project’s .gitattributes:

# Always keep our version of .uid files during merges
*.uid merge=ours

This tells Git to automatically resolve conflicts in .uid files by keeping the current branch’s version. The trade-off is that the merged branch’s UID assignments are discarded, but since Godot will re-associate resources with UIDs when the editor opens, this is usually safe.

You also need to register the merge driver in your Git config:

git config merge.ours.driver true

Another preventive measure is to ensure your .gitignore includes all generated Godot files that should never be committed:

# Godot generated files
.godot/
*.translation
*.import

The .godot/ directory contains uid_cache.bin, imported resource caches, and editor state—none of which belong in version control.

Rebuilding the UID Cache After Resolution

After resolving all conflicts and completing the merge commit, you need to let Godot rebuild its internal caches. Close the Godot editor if it’s open, then delete the UID cache:

rm -f .godot/uid_cache.bin

Reopen the project in the Godot editor. You’ll see the editor scan all resources and rebuild the cache. Watch the output panel for any errors about missing or duplicate UIDs. If you see warnings like Resource UID collision, it means two different resources ended up with the same UID. You can fix this by deleting the .uid file for one of the conflicting resources and letting Godot assign a fresh UID.

After the rebuild completes, open each scene that was involved in the merge and verify that all references resolve correctly. Pay special attention to scenes that reference resources created on both branches, as these are most likely to have broken UID links.

Team Workflow Recommendations

To minimize UID conflicts across your team, establish a few conventions. First, avoid opening scenes unnecessarily—the editor may generate or update UIDs just from loading a scene in the inspector. Second, when creating new resources, commit them to your branch promptly so other team members can rebase on top of your changes rather than generating parallel UIDs. Third, consider rebasing feature branches onto main before merging rather than using merge commits, as this gives Godot a linear history of UID assignments.

If your project is large enough that UID conflicts are a daily occurrence, you might also consider a pre-merge script that automatically resolves .uid conflicts. A simple shell script that runs git checkout --ours -- '*.uid' before the merge completes can save significant time.

UIDs are Godot’s way of keeping resource references stable through renames—once you set up the right Git strategy, they stop being a problem.