How to set up source control for Unreal Engine

Unreal projects combine text (C++, .ini, .json) and very large binaries (.uasset, .umap, textures, builds). Git handles the text side well and the binary side poorly. Git LFS patches some of that, but introduces pointer-file foot-guns and bandwidth billing that scales badly.

This guide walks through setting up USourceControl for an Unreal project from scratch. Setup itself takes about five minutes; your first full upload depends on project size. You only do it once per project.

There is almost nothing to do here. Close the Unreal Editor before you link the project: editor locks on generated files can interfere with the initial scan. That's it.

YourProject/
├── Saved/            # excluded (logs, crash dumps)
├── Intermediate/     # excluded (build intermediates)
├── DerivedDataCache/ # excluded (cooked asset cache)
├── Binaries/         # excluded (compiled DLLs)
├── Build/            # excluded (packaging output)
└── .vs/              # excluded (Visual Studio state)

What gets versioned: Content/, Config/, Source/, Plugins/, and the .uproject file. If your project already has a .gitignore, it is left alone and used as-is — you can edit the exclusion list at any time from the app's settings.

One thing worth checking if you bring your own exclusions: don't ignore __ExternalActors__/ or __ExternalObjects__/. Plenty of older community gitignores still list them from pre-OFPA days, and on modern UE5 that means losing your level data on every commit.

Create your first project to get set up. Once your account is ready, on the dashboard:

1. Create a new organization if you don't have one.
2. Click New project. Pick a name. It doesn't need to match your local folder name.
3. Copy the project key (starts with usc_). You'll paste it into the desktop app next.

Download the desktop app from usourcecontrol.com/download. On first launch:

1. Click Link project.
2. Paste the project key from Step 2 (you can find it again in the web dashboard under the project's settings). The desktop app authenticates with this key; there is no separate sign-in.
3. Browse to your Unreal project folder (the one containing the .uproject file).
4. Confirm.

This is the point where the app auto-detects the Unreal project and writes the exclusions described in Step 1. You don't need to configure .gitignore-style exclusions manually, and you don't need to have deleted anything by hand.

The app scans your project folder. You'll see a list of all files to be versioned, likely several thousand, plus any large binaries. Review the list:

• Verify nothing from Saved/ or Intermediate/ is in the list.
• Confirm your .uproject, Content/, Config/, and Source/ files are present.
• Type a commit message. "Initial project state" is fine.
• Click Commit.

The first commit uploads every file, so it takes a while on large projects (a 50 GB project on a 100 Mbps connection takes ~70 minutes). Subsequent commits are incremental and usually complete in seconds.

From the dashboard, open the Members section of your organization. Invite teammates by email; they get a magic link, install the desktop app, and join your project.

On their first sync, the app downloads the full project state to a folder they choose, usually a fresh Unreal project directory. After the initial sync, they open the .uproject in Unreal and work normally.

Role assignments are straightforward:

• Owner: billing and org-level control.
• Admin: can invite members, create and manage projects, and manage project keys. No billing access.
• Member: commits and syncs within assigned projects.

Unreal blueprints are binary .uasset files. They can't be merged, so when two people edit the same blueprint concurrently, only one person's work survives. Locking prevents this.

The flow, every time you edit a blueprint or level:

1. Open the desktop app, find the blueprint in the file tree.
2. Click Lock. Optionally type a reason.
3. Open the file in Unreal Editor, make your changes, save.
4. Back in the desktop app, click Commit. The lock is released automatically after a successful commit.

For a deeper treatment see Blueprint merge conflicts and how to avoid them.

First commit is slow.It's uploading the full project. A 50 GB project over a 100 Mbps upload takes around 70 minutes. Let it finish in the background.

App says a file is locked but I don't see the lock. Refresh the project view. Locks are server-authoritative; your client may be behind.

Someone has an old lock they forgot about. The quickest fix is to ask them to release it from their desktop app, or to commit the file. Org owners and admins can also break a lock through the locks API with force: true.

A commit is rejected as locked.Someone else holds a lock on one of the files you're pushing. The error names the files and who holds them; commit the rest, or wait for them to release.