This guide aims to teach how to use the Diff Tool that is available as a default plugin for Unreal Engine 5. It is meant for people who know at least basic git usage.
The Diff Tool is useful for reviewing Pull or Merge Requests and handling merge conflicts.
Limitations: The Blueprint Diff Tool will not show detailed hierarchy changes in Widget Blueprints. It also will not show changes to Animations and Bindings in Widget BPs.
It also is exclusive for blueprints. It doesn’t work for other graph-based assets that are not Blueprints (such as Material Graphs or Sound Classes)
Setup
You need to have Git installed on your computer, and your project must be in a Git Repository
- With the project opened, go to Edit → Plugins and search for the Git plugin;
- Add it to the project and reestart the editor;
- On the bottom right tab, click in Revision Control → Connect to Revision Control;
- Choose Git (beta version) on the Provider field and review your git information;
General Diff
When the local version of a blueprint has changes compared to the Upstream (which Unreal calls “Depot”), you can check the differences by right-clicking the blueprint, then going to “Revision Control” > “Diff Against Depot”.
You can also compare other versions that are not local by going to “Revision Control” > “History”, then selecting two, right clicking, and clicking “Diff Selected”
You can also compare other versions that are not local by going to “Revision Control” > “History”, then selecting two, right clicking, and clicking “Diff Selected”
The Blueprint Diff window will then open. It is split into three panels. The left panel is a color-coded list of changes, two right panels are a representation of each version of the blueprint
Changes that are made to graphs have two little graph icons to their right.
When you select these items, the graphs will be displayed as Read-Only in the two right panels, showing where in the graph each change was made. Each item in the list to the left matches a colored highlight in the graphs.
The list of changes is color-coded as such:
- White: No change
- Light yellow: Either a section with changes, or a non-graph item that was changed
- Light blue: A graph was added or removed
- Green: A node or link was added in a graph
- Cyan: A node was modified in a graph
- Red: A node or link was deleted from a graph
Merge Conflicts
The Merge process is slightly different for Widget Blueprints and is covered at the next section
Sometimes, two different branches end up touching the same blueprint. While ideally the team should coordinate to avoid that altogether, it can happen by accident.
For the purposes of this guide, we’re using GitHub as our git platform, but the information here should be easily adaptable for GitLab, BitBucket, Codeberg and others.
Such situation can be seen in a Pull Request that is blocked, for example.
In this scenario, I have a merge request from branch feature-2 that is intended to merge into main. However, a previous change to main, which happened after feature-2 was created, results in a conflict.
To fix it, I checkout feature-2, then pull main into feature-2. It shows me that Content/MyActor.uasset has a conflict. I then run git checkout --theirs Content/MyActor.uasset, which locally replaces the file with the version from main. This will allow us to run the Blueprint Merge Tool.
The conflicted file now has an icon of two yellow arrows pointing to each other. By right-clicking and going to Revision Control, we see that a “Merge” option is available.
Now we have four panels. The 3 to the right will each contain a version of the blueprint, and we have to select them. The first one automatically picks the local version. We should manually pick the other two to make our comparisons (I put the version before either change in the middle, and the feature-2 version in the right).
After that, we should see a comparison between the three versions. The graphs are read-only, but we can copy from them. So I’ll copy the change from the right-most graph, and paste it into the local version of the blueprint, via the normal blueprint editors
Fixing a merge conflict like that in a real scenario involves some manual work, but having the information of what was changed on-hand is extremely helpful.
After saving the edited blueprint, we can just commit it as a merge commit, and push it.
Widget Blueprint Merge Conflicts
When you issue the merge command, you may receive a message saying a particular Widget Blueprint has conflicts.
- On the terminal, issue the command:
git checkout --theirs path/to/file.uasset - On UE Editor, you will see two yellow arrows pointing to each other diagonally. Select the conflicted widget/blueprint and open History:
- Select the most recent commit and choose Diff Against Workspace File
- Now you should be able to compare all the blueprints nodes. Just copy all the new things to the blueprint that you are at the moment
