UE4 and source control

UE4 and source control

Postby BenChang » Thu Oct 22, 2015 3:30 pm

UE4 has built-in support for version control with Subversion, Perforce, and (beta) support for Git. This guide in the documentation shows how to enable it:


With some careful organization, UE4 can work very well with source control. As always, the goals are:

  1. Let everyone on the team combine their work
  2. Let everyone on the team see the whole project in progress so they know how their part fits in
  3. Organize roles and responsibilities for different features and assets cleanly
  4. Reduce merge conflicts (people overwriting or breaking each others' work)
  5. Keep a history of changes so if something breaks you can revert

Git, like most version control systems, was originally meant just for code, so working with binary files like UE4's .umap and .uasset files requires some extra care.

Setting up a UE4 project for git

In this workflow we'll create a new UE4 project, initialize it locally as a git repository, and then push it to a repository on BitBucket.

  1. In UE4: Create a new project (could be empty, or with template, with or without starter content, whichever you like)
  2. Enable source control: R-click on any asset in the Content Browser and select "Connect to Source Control..."
  3. From the Provider popup, choose "Git (beta version)"
  4. Click "Initialize Project with Git", with "Add a .gitignore file" checked. This will initialize your project directory for git, creating a .git and .gitignore in it. Remember that Git is a distributed VCS, so it's perfectly fine to start with a local directory before even creating a remote one.
  5. Click "Accept Settings"
  6. You may get a warning that says "We noticed that your auto-import settings are set up to detect source content changes on restart; this might cause unexpected behavior". I have no idea what that means, but I don't like unexpected behavior so I'll follow their advice and click "Don't Detect Changes on Startup"
  7. Now any assets in the content browser will have a little icon in the upper right corner,indicating whether it's up to date, staged for addition/updating, or is new and git doesn't know what you want to do yet. Everything will have a "?" icon, meaning that git knows it's a new file it hasn't started tracking. Maybe you want to add it, maybe not, your call.
  8. Create the remote repository on the BitBucket (or github, etc) website Log in the your Bitbucket account, and select Repositories->Create Repository.
  9. Give it a name and description, check the options for Wiki and Issues Tracker if you want, and create it
  10. The repository will be empty, so we'll need to push an initial commit either from a client like SourceTree, or the command line to get started. DON'T click the "Clone in Sourcetree".

      Using SourceTree
    1. Open the repository browser (Window->Show Repository Browser)
    2. Select "New Repository->Add Existing Local Repository"
    3. Select your UE4 project's local directory
    4. In the Working Copy view, you should see at least your .gitignore file in the list of Staged Files (possibly others if you're beginning with starter content), and more files in the Unstaged Files list.
    5. Create an initial commit - click "Commit" and enter a commit log message. Nothing will be uploaded to Bitbucket yet, that'll happen in the next step.
    6. Go to Repository->Repository Settings, click "Remotes", and click "Add" to add a new Remote
    7. You need the URL for the remote, which Bitbucket won't show you nicely until you have something committed into it, creating a catch-22. You can get it by expanding the "I have an existing project" link in the Bitbucket page. It will look something like this:

      Code: Select all

      Give it a name to match the repository name.
    8. Push. Check the box by "master" branch.
      OR Using Command Line
    1. Go into the UE4 project folder
    2. Code: Select all
      git remote add origin https://benchang@bitbucket.org/benchang/MyUnreal4Project.git

Project Organization

Tips for organizing and reducing merge conflicts

  • Plan out clearly who is working on each feature and asset
  • Organize your assets in subfolders in the Content folder. You can organize by type of asset, and also create subfolders for each team member for work in progress
  • Merge early and often, and assign one member the thankless job of managing all merging into master
  • COMMUNICATE with your team when editing Blueprints and Levels. These are the two most common places where unresolvable merge conflicts will appear, and where only one person should make edits at a time.
  • Level editing: You can break up a Level into sub-levels, which can all be combined into one main level. Each is a separate .umap file so multiple people can work on different sublevels at the same time safely. You can do this spatially ("Forest", "Town", etc), or logically ("Architecture", "Foliage", "Enemies", "Conversation NPC's". When they're linked into the main level they're all visible at once, but edits to an Actor in a sublevel are only stored in that sublevel, the main level doesn't change.
User avatar
Posts: 176
Joined: Mon Jan 17, 2011 4:48 pm

Return to Game Development

Who is online

Users browsing this forum: No registered users and 0 guests