How to use GitHub and Git with Unreal Engine 5

▶

will guide you step-by-step through the process of publishing and versioning your Unreal Engine project using Git and GitHub. Use the timestamps if you want to jump directly to the commands.

1. ❓ Why Should Video Game Developers Use Git?

As a software developer, I find the use of Git to be fundamental in modern programming. I'm surprised that many video game developers (especially indies) seem to avoid or not prioritize using Git and GitHub, when it offers crucial benefits, especially with engines like Unreal or Unity.

• Project Protection (Backup)
  • Git creates a complete version history of the code every time you decide to save a commit.
  • If a change or an update causes the Unreal project to stop opening (as happened to developer Knu), you can run git checkout [commit_hash] and instantly revert to a previous functional version, losing only the work from the last change.
• Log and Tracking
  • You have a historical record (git log) of all changes, allowing you to see the evolution of the project.    If you accidentally deleted code or need to check how a feature was implemented months ago, you can easily recover it.
• Collaboration
  • It allows multiple developers to work simultaneously on the same project without massive interference.
  • Essential for any team.
• Synchronization (GitHub)
  • GitHub or Bitbucket is a remote repository (in the cloud).
  • If your hard drive fails or you lose your computer, your work will always be safe on the Internet, allowing you to synchronize it on any other machine.
• Work on Multiple Machines
  • You can effortlessly synchronize your work between a desktop PC, a laptop, or a Mac.
  • If you do level design on your laptop and then code Blueprints on your PC, you use a simple git pull and git push.

2. ️ Installing and Configuring Git and GitHub

A. Install Git

• On Mac: Git comes pre-installed. If you need to update it, you can use homebrew (brew install git).
• On Windows: Download the installer from the official website. During installation, make sure the option to add Git to the PATH is checked.
• Verification: Open your terminal (or cmd) and run git. If you see the list of commands, the installation was successful.

B. Create a Repository on GitHub

GitHub (or any remote repository) is where we will save our code in the cloud.

1. Go to GitHub, create an account if you don't have one.
2. Click on "New Repository" (+).
3. Give your project a name.
4. Select "Private" if you don't want your code to be publicly accessible (ideal for games you plan to sell).
5. Click on "Create Repository". The next screen will give you the necessary commands to link your local project with this repository.

3. ️ Prepare and Sync your Unreal Project

A. Enable Git in Unreal Engine

• Open your Unreal Engine project.
• Go to "Version Control".
• Select "Git" as the provider.
• Unreal Engine should initialize the Git repository for you (by running git init internally). If it gives you an error, make sure Git is installed correctly.
• Accept the configuration (blue button).

B. First Publish (Link and Upload the Project)

You must run the commands in the root folder of your Unreal project (where the Content and Config folders are located).

Link the Remote Repository: Copy the command provided by GitHub:

git remote add origin [REPOSITORY_URL]

Stage Files (Staging): Track all files in the root folder for the commit.

git add .

Create the Commit (Local Version): Save the changes with a descriptive message.

git commit -m “Initial commit of Unreal Project”

Synchronize with GitHub (Push): Send the local version to the remote repository.

git push -u origin main

Warning! The first git push can take a long time since Unreal projects are large (several GB). It is recommended to do this immediately after creating the project to upload fewer files. Unreal will prompt you to authenticate with your GitHub account in a pop-up window.

Cloning the Project on a New PC (Alternative Method)

If you need to get the project on another machine:

Fast Way (Recommended): In the new location (e.g., Documents), use the git clone command followed by the repository URL:

git clone [REPOSITORY_URL]

Slow Way (If clone fails): Due to the large size of Unreal projects and possible network interruptions, git clone may fail. If this happens, simply copy the entire folder of the original project (which already includes the .git folder with all the history) to the new location using a hard drive or pendrive. Once copied, use git pull and git push normally.

Summary

Additional Benefit: Multi-Machine Synchronization

And a third benefit you get for free is that if you're like me and work on multiple computers (I use three in this case), you can easily synchronize them across any of the three without any problem.

First Steps: Unreal Project Created

So, there you have the advantages. The next thing is what we need to do to use this. Obviously, you have to have your project created in Unreal. I'm taking that for granted. We're already at the second point.

Step 1: Create a GitHub Account

The next thing is to come here to this page called GitHub, which is where your project will be stored, remotely, so to speak. It's completely secure, don't worry about that. There are many similar pages, like GitLab, but this is the most used one, the one I would recommend, although you are free to check out the rest of the options. Here's the usual: I already have an account here, but you register, authenticate, or create an account, and little more to say. Then, you will create the repository for your project. You can set it to private if you wish.

Step 2: Verify or Install Git on your Mac

How to install Git: if you're on a Mac, you might already have it there. You simply have to type git in the terminal and little more to say. Likewise, we'll see some commands now, but again, I'm taking the configuration part for granted.

Initialize Project in Unreal

In this case, I will show you a short video so it's a bit clearer. So, I already created the project and all that stuff here.

The first thing we have to do, and the only thing we have to do here, is in the corner where it says Version Control, and you add the Git one here, add the repository, and that's it.

Next point, close the Unreal project and use a cd to navigate to the project location.

And the necessary commands

git status 

To see the changes made.

git add.
git commit -m “”

    To add the changes

git push

To synchronize the changes, remember to add the remote as shown in the video so you can push the changes to the GitHub repo.

Important: Files should not be larger than 100 MB; in fact, an alert is triggered starting from 50 MB.    

You're Developing Your Games in Unreal Engine/Godot/Unity Wrong

   

▶

I want to share a recent situation I experienced while developing, which underscores the critical importance of using code backup systems like Git and GitHub.

I was editing a simple Blueprint for a portal in my world selection menu. Suddenly, Unreal Engine crashed, which is common in the engine. The problem came when I tried to reopen it: the file had become corrupted on my Mac (although luckily I could open it on Windows, indicating a platform issue rather than the file itself).

This incident reminded me of the need to protect the work.

The Risk of Developing with Game Engines

The situation I experienced is the worst-case scenario for any developer, and the risk is even greater in engines like Unreal or Unity:

1. File Corruption: A crash, a failed update, or an editing error can corrupt a vital project file.    
2. Binary and Structured Files: Unlike plain text code (like in Laravel or Flutter), Unreal files are often binary or internally structured in a way that is incomprehensible and difficult to repair manually (e.g., compiled Blueprints or internal configuration files).    
3. Loss of Time: Trying to recover a level or a complex Blueprint can take days, leading to frustration and the decision to start over.    
4. Developer Anecdote: A well-known indie developer (Knu, who uses Unity) commented that he lost several hours trying to rescue a project that simply refused to open. If he had used Git, the problem would have been solved in minutes.    

Git and GitHub: Your Digital Life Insurance

The use of Git (local versioning) and GitHub (cloud backup) completely eliminates this worry.

a. Instant Recovery (Git Checkout)
I have more than 245 commits in my Unreal project. If a file gets corrupted:

• No Worry: I don't have to waste time "giving birth" to a solution.    
• Go Back to the Past: I simply copy the hash of the last stable commit, run `git checkout [commit_hash]`, and the project immediately returns to a safe working state. We only lose the work done since that last commit, but we save the entire project.    

b. Cloud Backup (GitHub)

GitHub adds a layer of protection:

• Disaster Recovery: It doesn't matter if the computer or even the country explodes; the project is safe in the cloud.    
• Synchronization: I can use another computer and do a simple `git pull` to get the changes, or directly clone the repository on a new machine.    

Repairing a Corrupt Git Repository in Unreal Engine

Working with Unreal Engine and Git can be a challenge due to the large size of binary files. It is common to encounter errors that completely block the workflow, especially on external drives or after an unexpected shutdown.

The Problem: “Unable to open loose object”

The error begins with a critical message: error: unable to open loose object ... Function not implemented when performing a git pull.

This failure indicates that the local Git database has been corrupted. The file system cannot read a specific object and, as a result, Git loses the ability to understand where the project currently stands (fatal: Could not parse object 'HEAD').

The Repair Strategy

When the damage is extensive, trying to repair object by object is inefficient. The most robust solution is to reinitialize the Git container without touching your working files.

Step 1: Reinitialize the Repository

The first thing is to delete the hidden .git folder (which contains the corrupted database) and create a new one from scratch:

# Delete the corrupt database
Remove-Item -Recurse -Force .git

Or delete the .git folder (or rename it and move it outside of the project)

# Create a new Git container git init # Re-link your remote server git remote add origin https://github.com/libredesarrollo/ue-reina

Step 2: The challenge of conventional Fetch

When attempting a normal git fetch on large projects, the connection is likely to be interrupted with errors like: error: RPC failed; curl 56 ... server closed abruptly.

This happens because Git attempts to download gigabytes of history all at once, saturating the buffer or the connection.

Step 3: The Definitive Solution with git fetch --depth 1

To avoid connection collapse, we use a Shallow Clone. This command downloads only the current state of the files, ignoring thousands of old commits.

# Download only the latest "snapshot" of the project to avoid network errors git fetch --depth 1 origin main

Step 4: Synchronize the files

Once the fetch is successful, we force our local Git to recognize those files:

git reset --hard origin/main

Conclusion

If you work in Unreal Engine, remember that git fetch --depth 1 is your best ally for unstable connections or heavy repositories. Once the project is stable, you can recover the rest of the history if you wish with git fetch --unshallow, but to continue developing, the shallow version is more than enough.

⏱️Key Recommendation: Start Now

It is essential to adopt the habit of backing up the code from the beginning of the project.

Reason: Unreal projects grow very fast. If you wait until you have several Gigabytes, the initial upload process (doing the first `git push`) will become slow and tedious, requiring an excellent Internet connection and a long waiting time.