Git with Unreal Engine 5

Git is a version control system that allows you to collaborate on an Unreal Engine project. In this guide you will learn

• What Git and GitHub are
• How Git compares to Perforce
• How to use it in your team projects

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.

Git vs 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.

Facts about Perforce

It's the industry standard for AAA game development. Perforce has been in the game business longer than Git, so it's dominant there.

It has great access controls due to it's centralized design. Where Git is designed as a decentralized system, meaning that once you have access to the Git repository (the place where you store your project files), you have access to everything. In Perforce, you can instead grant permissions at the folder level.

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.

How to use Git with Unreal Engine

There are three things you need to do.

1. Connect to GitHub or an alternative
2. Install the Git desktop application of your choice
3. Enable the Unreal Engine integration (optional)

Choosing a Git cloud storage provider (e.g. GitHub)

While GitHub is the most popular platform, it has two main problems

1. 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.
2. You cannot easily clean up your storageGitHub charges $5 per 50GB of storage and traffic. As you work longer on your project, files in your history will add to your storage needs. There is currently no "easy" way to clean up these files. GitHub recommends that you delete your repository and create a new one.

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, based on the experience of our users, it can sometimes be tricky to set up.

If you need complete control over your files, a self-hosted Git server is the best solution. In the next section, we will show you how to set up Azure DevOps.

Pick a Git Desktop Application (Git Client)

There are more or less 36 applications listed on the official Git website. In this article we will use Anchorpoint. We are the developers of Anchorpoint, but we will try to give you objective arguments for and against using it.

Anchorpoint is not for you if

• You need advanced Git features like rebasing, more staging controls, or submodules
• You want a completely free application.

If this sounds like you, you might want to take a look at SourceTree or GitHub Desktop.

On the other hand, Anchorpoint makes sense for you if you

• Are new to version control and have non-technical team members
• Need file locking
• Want to organize and version your art assets (Blender, ZBrush and Substance files)

Configure Unreal Engine

Use One File Per Actor (OFPA). 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.

If you want, you can also use the Unreal Git integration. Normally, it's enough to go to your Git client and commit and push all files to Azure DevOps from there. However, if you want to commit (not push) the files from Unreal, see the status of a file, and go back to older versions of a single asset, you can do that from the Git integration. To push your files to Azure DevOps, you have to do it from the Git client anyway.

Keep in mind that the Git integration will cause longer file save times because it will always copy to a Git cache.

Also, configure Git integration AFTER you have created the Git repository of your Unreal Engine project in Anchorpoint.

How to use Git and Unreal Engine with Azure DevOps

This tutorial will show you how to set up Azure DevOps as a cloud storage provider. When creating an account on Azure DevOps, we strongly recommend that you don't link an existing Microsoft-related account (e.g. from GitHub). We have seen this cause so many access errors. The best way is to create a completely new account that has never been associated with any Microsoft service.

How to work in a team

The workflow is quite simple

1. You work in Unreal Engine
2. Your changed files are locked for everyone else
3. You go to Anchorpoint, write a message about what you did, and push those changes to Azure DevOps.
4. Your team member gets a push notification and a big blue "pull" button
5. Your team member will pull your changed files to be in sync.

If you're both ignoring the file lock and working on the same file, you're in a conflict state that you need to resolve. Anchorpoint will show you conflicting files in a conflict manager.

If you want to go back to an earlier version, you can click on a previous commit and revert it. Anchorpoint will create new modified files representing the reversed state. For example, if you made a commit that deleted a file, and you want to revert that commit, Anchorpoint will restore the file.

What about Git LFS and a .gitignore?

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. 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.

Workflow recommendations

Don’t go crazy with branches

If you are a small team (less than 10), put all artists on a single 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.

The developer should only do the branching

The developer is the technical master and will have a better understanding of branches. It's hard to explain the concept of branches to an artist. Just let them work on a branch and not change it.

Push and pull often

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.

Write meaningful commit messages

This 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.