Skip to main content

Using Git Source Control In Unreal Engine

🚪 Prerequisite Knowledge

  1. Unreal Engine 5 Fully Installed with all it's development dependencies

    📎 Unreal Engine 5 Installation

  2. Git LFS is installed.

    📎 Git LFS

  3. Unreal Engine Git Plugin Installed

    📎 Installing Git Source Control in Unreal Engine 5

❓ Key Question / Problem / Issue

  1. How to use git plugin in Unreal ?
  2. How to add file to source control ?
  3. How to avoid Conflicting change ?
  4. How to Lock file from other people changes ?
  5. How to modify file tracked in source control ?

✅ Expected Output/Definition of Done

Reader able to setup Git Source Control in Unreal Engine 5

🎁 Resulting Solution

Unreal Engine Git Usage Best Practices

  1. Don't check out files marked with !

    unsynced files

    pull latest changes to remove this mark

  2. Always Pull latest Change Before modifying / Checkout any files

  3. Always Check Out file you've changed.

  4. Always Pull Before Submitting Changes

  5. Utilize Unreal Content Drawer Filter function to manage your version managed files Content Drawer Filters

  6. Utilize git GUI (e.g : Fork, and Tortoise Git to check file source control status) Git GUI

Activating Git Plugin (Per-Device & Per-Project Setup)

with Git plugin installed you need to follow these step to activate Git Plugin Source Control for Unreal Engine

  1. Open Project.
  2. Activate the source control plugin with click Source Control off > Connect to Source Control.. Untitled
  3. Then select Git LFS 2 as a Provider. Untitled
  4. The popup contents would change, you just have to set the Input field next to Uses Git LFS (Its possibly filled by broken text) with your git Full Name. Untitled

    GateGit (GitLab) Full Name Example (Highlighted with red Underline) Untitled Untitled

If there’s additional input or button that contains initial commits, its possibly your UE plugin is not connected to source control or git status not tracked. Make sure you remote to the right repository, git is not error and git LFS is installed.

Checking your source control is active

To ensure you can utilize Source Control Plugin

  1. Check Source Control Status Have Check Mark Icon in it (bottom right of Unreal Editor window) Version Control Ready

  2. Try Checking out a file and ensure that file is checked out properly by your full name.

    • it should look like this.

    Proper Checkout

    • and NOT like this

    Failed Check Out

Source Control Icons Explanation

If source control is fully connected, you may seen various icon on top-right of the assets. Here is the icon shapes and its descriptions as you can see at the image below.

Untitled

Adding Files

To start adding file to source control simply follow these steps :

Ensure to Pull / Refresh the latest changes before Adding, Modifying, Renaming, Deleting any assets

  1. Create / Add / Import File you want to distribute through source control

    Untracked File

    Files will be marked with yellow ? symbol when added

  2. Select file(s) / folder(s) you want to add

    select file to add

  3. Right-click to open the context menu then select Mark For Add menu

    Mark For Add File

    Mark for Add folder

  4. your file will be then marked with Red + symbol

    File Added

  5. Submit your content following Submit Content Section

Checking-out (Locking) and Modifying Files

The main way to share content with collaborators is via the Content Browser. All source control operations are accessible via the context menu for files and folders.

Manual Check Out

To Check Out a file (i.e. lock it for editing), Right-click on the asset and then select the Check Out option.

Untitled

Prompted Check Out

  1. When you edit asset, there’s pop a notification to check out these asset.

  2. click the Check-out link, then you will be presented with this dialog: Untitled

  3. Select one of the three button (check the descriptions of each button below) Untitled

    Avoid selecting Make Writable as it would save your change without locking the file, nor marks it as modified file in unreal engine

    Only use this when you know what you are doing !

  4. If you select Check Out Selected button, Icon would be added to your asset thumbnail Untitled

    And would be there till you push the asset (check-in) or discard (revert) your changes.

Delete files

  1. If you delete any file, you would see the Delete Assets dialog. It will tell you the asset data, like name, class and refferences of the file you delete.

    if you are sure to delete the files, select Force Delete button.

    Untitled

  2. Deleted File will also be checked out automatically You should also submit file deletion changes to the source control

    Submit your changes following Submit Content Section Untitled

Move/Rename Files

  1. When you move/rename file you will be prompted to check out the file. Move or Rename Checkout

  2. ensure to checkout the orignal file names / directory you renamed / moved this will checkout (lock) the old file name/locations to ensure other people doesn't modify it anymore.

  3. Moved/Renamed files will still need to be Mark for Add described in Adding File Section

    otherwise it will only count as file deletion.

    moved or renamed files

  4. These change need to be submitted, these steps are described in Submit Content Section

    Changes need to be submitted before applicable to other developer machine.

Submitting Content to Source Control

Submitting to Source Control in Unreal Engine is a vital part of the Source Control process. If you do not submit anything to Source Control, other users will not be able to see what you have been working on or created.

To submit all checked out asset follow these following steps :

  1. go to Source Control at the bottom-right of UE editor

  2. Press Submit Content.

    Untitled

    This will scan your project and the Engine for changes made to assets that can be submitted and then present you with the Submit Files dialog.

    Untitled

  3. Fill the change list description (it will be a message commit) and Submit.

  4. Once you submit it, all of related assets (checked out or new file) and its checked would be committed and pushed to the repository.

Additional Source Control Commands

When using right-click on a single (or multiple) file

  • Check Out Lock file(s) so other user can’t check-out, useful to prevent conflict. It’s advisable to Check Out file before editing/working on it.
  • Check In Submit (Commit & Push) selected file(s), also Unlock the file from Git-LFS
  • Sync Synchronize (Pull) selected file(s). If the file(s) is referenced by other files, the referencing files will be synchronized too.
  • Refresh Refresh the current file status/icon
  • History Show the changes made to this file. Right click on any history item to show popup menu to see changes between selected commit with previous commit or current working file
  • Diff Against Depot See side by side differences between current working file and last committed one.
  • Revert Discard changes and unlock file

(Optional) Configure Automate Check Out File on Asset Modification

you can set the editor to automatically check out files on Asset Modification by enabling Automatically Checkout on Asset Modification.

to enable this you need to follow the following steps :

  1. Open Editor Preferences Untitled
  2. Click on Loading & Saving scroll to Source Control. Untitled

Frequently Asked Question / Issue

Binaries Update Required

Solution

  1. Close your unreal engine.

  2. open your git client (fork / source tree/ gitkraken)

  3. pull changes from your git client

    • Ensure to always check rebase instead of merge
    • ensure your local change is empty to avoid rebase conflict

  4. push your change after your graph are rebased like below

  5. open unreal and submit content again to ensure file are unlocked.

Back to top