Git with Unreal Engine 5

Git is a version control system that allows you to collaborate on an Unreal Engine project. This guide is the result of five years of helping our users manage their Unreal Engine projects with Git. You will learn:

• What Git and GitHub are
• How to upload your Unreal Engine project to GitHub
• Workflow recommendations for teams

Why do you need version control?

Version control, source control or revision control (it's all the same) is the right way to collaborate in Unreal Engine. You cannot put your files on a NAS or Dropbox and work together, because that would lead to file corruption and constant interruptions due to constant syncing.

To avoid desperation, a version control system allows you to

• Make backups of your project in case your files get corrupted
• Synchronize between computers
• Share your files with your team
• Force you to work properly by committing your work at least once a day
• Add documentation to your work
• Facilitates team collaboration with features like file locking, so you never lose work because two people have been working on the same file at the same time.

There are many version control systems available. The 4 most common are Git, Perforce, SVN, and Unity Version Control (Plastic SCM).

What is Git and what is GitHub?

You have probably heard of GitHub. GitHub is a cloud service based on the Git version control system. It is part of a huge ecosystem around Git. GitHub is the cloud storage for your files and can do many other things like task management and automation.

When you use GitHub, you use Git version control. In addition to GitHub, you also need a desktop application that pushes and pulls files to and from GitHub.

Prerequisites

There are three things you need to have

1. A GitHub account
2. A desktop application that uploads your Unreal Engine project to GitHub, so called Git client. This can be Anchorpoint, Fork or SourceTree.
3. The Unreal Engine Revision Control plugin (optional), if you want to submit files directly from the Unreal Editor

How to upload your Unreal Engine project to GitHub

In this example we will use Anchorpoint (of course, because we are the developers of it) as a Git client, but the process is pretty similar when using other Git clients. We will:

• Create a GitHub account
• Create a repository
• Push our files

Setup GitHub

Go to GitHub.com and create a free account. No more. You don't need to create a repository, because we will do that from Anchorpoint to save us a few clicks.

Connect your Git client with GitHub and create a Git repository

Download Anchorpoint, install it and create an account. Then connect to GitHub.

You will need to authorize "Anchorpoint Software" and "Git ecosystem". The first one is to give Anchorpoint the permission so that it can create repositories on your behalf. The second one is for your Git credentials, so that Anchorpoint can push your files to the GitHub repository.

Once you have done it, you should see a "Connected" tag next to the integration.

Upload your Unreal project files to GitHub

Now, we need to create a Git repository. In Git lingo, this is basically your project folder containing all your files, and it's called a 'repository' as it's the source of truth of your project.

When you create the project in Anchorpoint, the Git repository will be created on GitHub automatically. You can skip the step of inviting members — this can be done later.

What is a .gitignore?

In Unreal Engine projects, a ".gitignore" file tells Git to skip files and folders like "Binaries/, DerivedDataCache/, Intermediate/, and Saved/". These are auto-generated by the engine and don’t need to be versioned, which keeps the repo smaller and avoids conflicts.

Once you have the project (or repository) ready, you can upload your Unreal project. Anchorpoint calls that step "Sync" which is basically a chain of 3 Git commands (add, commit and push). We will explain that later.

Once your files are on pushed successfully, you can go to GitHub and check if all your files are there. That's it, now you can use version control on your Unreal Engine project with GitHub.

Using the Anchorpoint revision control plugin for Unreal

Rather do not use the integrated Git revision control plugin that comes with Unreal. It's marked as beta for a reason. The issues of that plugin are that:

• You will still need to install Git/ Git LFS and configure it manually
• It cannot lock files
• It slows down your workflow after each save

An alternative is the Git plugin from Project Borealis if you are using another Git client.

How to install the Anchorpoint plugin

1. Go to Fab website and add Anchorpoint to my library.
2. In Epic Launcher navigate to Unreal > Library and scroll to the bottom and on Anchorpoint click install to engine.
3. After starting your project, go to Edit / Plugins, search for Anchorpoint and activate it.
4. After restarting the project, click on the revision control in the bottom right corner of Unreal.
5. Select Anchorpoint (Git) and apply. The Anchorpoint desktop application will launch in the background.
6. If you have the project set up in Anchorpoint, the plugin will recognize it and you can start working.
7. Now every time after you make changes and save/check out, you can click the revision control button and commit the content.

Workflow and setup recommendations

Once your files are on GitHub, here are some recommendations for you and your team to consider when using Git. Some of the recommendations defined here are inspired from the Epic Games on “Setting up a game studio the Epic way” article and video.

A popular version control practice is trunk-based development, where developers merge small, frequent updates into a core "trunk," or main branch. Based on this, we can for example, let the artists work on the main branch if there aren't too many of them, coders could each have a specific branch if they're developing major features, or just a coding branch (plus maybe an engine branch for modifying the engine source code), and for further tweaks, a release branch where it's only for merging from the main, with no edits allowed.

Your average day looks like this

1. You work in Unreal Engine.
2. Your changed files are locked for everyone else.
3. Once you finish your work, you sync your changes
4. Your team member will pull your changed files to be in sync. The files are now unlocked for them.

Use one file per actor

One File Per Actor (OFPA) was introduced in Unreal Engine 5. There is no reason not to use it, as it will split your map file into smaller actor files. This allows you to work with multiple people on the same map at the same time. If you are using World Partition, OFPA is enabled by default. If not, you have to enable it in the world settings.

Keep the amount of branches to a minimum

If you are a small team it's totally fine to work on the main (so called trunk branch). If conflicts arise, they can be resolved immediately. You don't want your artists to work on their own branch for a week, and then spend a whole day merging and resolving conflicts when they've forgotten what they were working on. If there is a conflict, resolve it immediately.

Developers can work on feature branches. Based on the trunk-based-development concept, they are merged on a daily basis. In a bigger team, you can use Pull Requests for that, where you incorporate a code review process.

Push and pull often and write meaningful commit messages

Do this at least once a day. Don't push everything at the end of the week. You will create a lot of conflict. Regular pushes and pulls will keep everyone on the team in sync.

Writing meaningful messages is a hard habit for artists to get into, because it's natural to write a message like "made some changes”. Getting into the habit of writing good commit messages will make the whole game development process transparent and avoid confusion. It's the same as naming your files.

Maintain a fixed folder structure and change it as little as possible

Changes in project structure can create massive issues and file conflicts. The best approach is to set up a style guide for your project structure. If you need to change that, nobody should work on that project at the moment. You need to communicate it in your team. Otherwise this can lead to file conflicts.

Checkout Workflows - why they are necessary

When using the Anchorpoint plugin for Unreal Engine, a checkout dialogue will appear after you have modified and saved a file for the first time. This workflow originates from Perforce and is based on an exclusive checkout/check-in mechanism for editing files. This method does not exist in Git. Rather than checking out a file, Anchorpoint locks it to prevent other team members from modifying it.

The main reason they exist, and why file locking exists, is that binary files cannot be merged. Without these mechanisms, you would have to discard one person's work, which would lead to frustration and wasted working time.

Syncing editor binaries (Unreal Game Sync)

If you are working on a C++-based project — or even more, if you are using an Unreal Editor version that you have compiled from the source — using a solution to distribute the Editor and Game binaries will speed up your workflow immensely. In the Perforce world, this is achieved using Unreal Game Sync. Anchorpoint comes with a plugin that allows you to share editor binaries with non-coders so they don't need to install Visual Studio and waste time compiling.

CI/CD systems

In a studio environment, it is useful to have an automated build creation process so that builds can be quickly handed out to QA or other stakeholders. GitHub Actions allow you to configure such a build pipeline. Jenkins is often used on Unreal projects. For some time, Epic has also developed its own solution called 'Horde' that comes with built-in build graph support.

Limitations of GitHub

This is about GitHub and not Git itself. While GitHub is the most popular platform, it has two issues:

File size limitations

There is a hard limit of 4GB per file. This limit applies to the GitHub Team plan. The Pro and Free plans have a 2GB file limit, and the Enterprise plan has a 5GB file limit. You will not be able to upload files larger than this.

Repository limitations

With the free plan, you get 1 GB of storage. With Git LFS activated, you get 10 GB of storage and bandwidth for your repository. If you exceed these limits, you will need to pay $0.0875/GB for bandwidth and $0.07/GB for extra storage. Unreal Engine projects can grow quickly, so you might look for alternatives.

Alternatives to GitHub for Unreal Engine projects

Thanks to the Git ecosystem, we can choose an alternative. Azure DevOps doesn't charge for LFS storage, so we don't have to worry about storage management. However it can sometimes be tricky to set up.

If a high-quality service is important to you, another good alternative is Gitea Cloud or Assembla. Both provide excellent support and security options, and neither suffers from file size limitations.

If you need complete control over your files, a self-hosted Git server is the best solution.

Frequently asked questions

How is Git different from Perforce?

We have a more detailed Git vs. Perforce comparison that includes cost. Here are some hard facts about both systems.

Facts about Git

It's open source and used by 93% of all software development projects. There is a huge ecosystem of tools, cloud providers, and communities. There is no vendor lock-in. You can move your Git projects to another hosting provider if you are not happy with the first one.

Git does most of its work locally, so it's fast. It is fast at creating branches, local commits, and history lookups. Of course, this speed improvement does not count for file transfer, because that depends on your internet connection.

What both can do

Both scale to TB-sized projects with thousands of participants. Perforce is known for this, and with recent developments in Git (with features like Git LFS, sparse checkout, and partial cloning), it works on large projects as well. We have tested it on terabyte-sized repositories, and projects like the Linux kernel that use Git have over 15,000 contributors.

Both have integration with the Unreal Engine, allowing you to submit changes and see the status of files directly from the editor.

What is Git LFS?

Anchorpoint does all this automatically, but if you don't want to use it, you'll need to install Git LFS, which stands for Git Large File storage and is the extension for handling binary data.

To use Git LFS, you need to mark the appropriate file types in the .gitattributes file. This is the configuration file for Git.

What is a .gitignore?

The .gitignore file filters file types and folders that should not be uploaded to the git server. In most cases these are cache files created by the Unreal Engine. Here you can download a preconfigured .gitattributes and .gitignore file. Place the .gitattributes file in the root folder of your repository and the .gitignore file in the folder where your Unreal Engine data resides.