Creating a Git Repo for your Mod

Once you have started working on a mod of your own, you should set up a repository to store your mod’s files.

This page walks through creating a Git repository for a mod and enabling the engine’s Git integration. It assumes you have already followed the Getting Started guides for creating a simple mod and that you want to take an existing mod and place it into a git repository.

If you’re new to git, check out the Learn Git page first.

Experienced Git users, skip to this section.

Creating a Repository and Adding your Files

In order to get our mod’s files into a git repository, we will first need to create a repository. There are multiple ways to do this, but the easiest is to start by creating a remote repository on GitHub, then cloning it to your local computer.

Create the Remote Repository on GitHub

GitHub’s own documentation explains how to create a repository.

The bullet-point list below will serve as a reference as you follow the documentation here. Stop following those directions once you get to the "Commit your first change" section.

Here are some notes about what decisions to make while following the GitHub documentation:

  • When prompted, you don’t want to create your repository from a template.

  • (Step 2) Your repository name should be your mod reference. It is possible to use a different name, but doing so will require more work later.

  • (Step 4) We suggest you leave your repository as 'Public' so others can learn from your mod, help you if you get stuck, and write extensions to your mod.

Creating the Local Repository

In order to get started storing out mod files in a Git, we need first need a local repository on our computer to start tracking our existing plugin files. There are a couple ways to do this, but Option A is the suggested approach.

Option A: Have GitHub Create the Repo For You Via Cloning

Setting up a local repository that is connected to GitHub usually requires running some commands in the command line, but this approach allows us to skip these steps by bringing in a folder that GitHub already created for us, then moving our own mod’s files into that folder.

Make sure you have the Unreal editor closed before proceeding.

Locate the folder for your mod in your Starter Project’s Mods/ folder, for example, Mods/YourModReference/. Rename your mod’s folder to something else, for example YourModReference_Original/. We are renaming this folder because your git client will complain if you try to clone into a folder that already contains files. As such, we are temporarily giving the folder another name so the clone process doesn’t complain.

Now, use your git client of choice to clone the remote repository you created on GitHub inside your project’s Mods/ folder. Directions for doing this in GitHub Desktop can be found here. Assuming your GitHub repository is named TheRepositoryName, you should now have two relevant folders in your projects Mods/ folder:

  • The repository folder you just cloned, TheRepositoryName/

  • Your original mod folder which you renamed to YourModReference_Original/

If the repository folder is named something other than your mod reference, you should rename the folder to exactly match your mod reference. For example, if the folder you just cloned was called TheRepositoryName/, rename it to YourModReference/. This folder will become your mod’s folder from now on, so it must obey the usual Mod Reference naming rules. Note that your git client may lose track of the folder if you rename it, in which case you will need to re-add the folder to your git client. In GitHub Desktop, this is done via File > Add Local Repository…​.

The (possibly recently renamed to) YourModReference/ folder should contain just a README.md file, or, if you have showing hidden files enabled on your system, you should see also a .git folder. It is suggested that your ficsit.app mod page contents be copied into the README.md file, explained in more detail here.

Now, move the contents of your plugin from the YourModReference_Original/ folder into the YourModReference/ folder.

You have now successfully moved your plugin files into a local git repository, but they are not yet tracked, nor stored on the remote. It’s safe to delete the now-empty YourModReference_Original/ folder.

Launch the editor and package your mod to make sure everything is still working. If your plugin isn’t appearing in the Alpakit list, make sure that the folder for your plugin is named exactly your mod reference.

Option B: Create the Repository Locally and Push it to GitHub

This option will not be explained here, but exists as a heading since it is a valid approach.

If you chose this approach, look for other resources online to help you. It will involve configuring your local repository to point to the remote on GitHub.

Gitignore File

In order to keep temporary or user-specific files out of the repository, git uses a file called .gitignore to keep track of what files to exclude.

If you created your mod with the Alpakit wizards, it will have already created this file for you. If not, you can pick one up here.

You can optionally learn more about how this file works here, which could be helpful if you want to exclude additional files.

Commit the Existing Files

Now that you have your repository set up, you need to commit your existing files to it. Committing is the process of telling git that you want to save the current state of your files.

Your first commit will involve committing all of the files for your plugin, since they had not been tracked by git before. In the future, only files you have changed since the last commit will appear for you to commit.

Directions for committing files in GitHub Desktop can be found here. Regarding the Discarding Changes section of those docs, avoid doing this when the Unreal Editor is open, as it may attempt to re-create the discarded files.

The gitignore file should have already excluded temporary files and build-related files for you, but you may have to stage them for commit before they will disappear from your git client’s status list.

Pushing

Once you have committed your files, you need to push them to the remote repository on GitHub. This backs them up on the GitHub servers and makes them available to other users if your repository is public.

Directions for pushing files in GitHub Desktop can be found here.

Enable UE VCS Integration

The custom engine version used in the Satisfactory Modding community has been modified to allow Unreal Engine’s Git integration to recognize and work with multiple git repos in a single project.

To enable, navigate to "Tools" > (Source Control heading) > "Connect to Source Control…​". Select Git from the dropdown, then click "Accept Settings".

You can now right click on assets in the Content Browser to view their change history, diff assets, and more.

Git Workflow

Congratulations, you have now set up your local repository and pushed it to GitHub. Test it out by viewing your repository in the web browser - you should be able to see your mod’s files.

If something isn’t working, contact us on the discord for support.

Here is a brief overview of how to continue working with Git in the future:

  1. Make changes to your mod as normal

  2. Open your Git client to commit your changes. When is a good time to commit? That depends on your preference. Consider committing if you have made a significant change, or if you are about to make a significant change and want to be able to revert it easily.

  3. Push your changes to the Remote Repository

End of currently written content

This is the end of the currently written content for this guide. If you have suggestions for how to improve the guide, or if you found part of it confusing, please contact us on the discord. Below are a series of additional notes intended to be used in future updates to this guide that do not yet have a home.

Experienced Git Users

This section assumes that you already know about the repository creating, committing, and pushing processes.

Use the git tool you are comfortable with.

Be mindful of merge conflicts and branches in the context of Unreal Engine. Most Unreal Engine asset files are raw binary files, which means git diffing them must be done inside the editor. The editor has a pretty decent built-in merge resolver, but you must be able to open the editor to use it. You’ll have to resolve conflicts and compile errors on the C‍+‍+ side first to build a working Development Editor copy to open, and the editor could get confused if information from C‍+‍+ parent classes change.

Panakotta has directions on setting up UE to launch in diff mode as a git diff/merge tool here.

Unsorted Notes

Repository readme

Both your repository’s readme and your ficsit.app mod page are formatted with Markdown. It is suggested that the contents of your mod page be stored in README.md, or alternatively in a separate MODPAGE.md file if you have something else you want to put in your README.md.

UE4GitDiff

A tool that runs the UE diff interface from git command line.

https://github.com/mircearoata/UE4GitDiff

It currently has an issue in finding the project and engine when using symlinked plugin folders and git bash. When cd-ing inside a symlinked folder, git bash will pass the real path to UE4GitDiff, rather than the plugin path inside the SML project. The workaround for this is to either run it from command prompt or powershell, or to open git bash directly in the plugin folder and not cd from there.

Nested Mod Folders

It’s possible to keep the files for multiple mods in one git repository by having a parent folder as the git repository with a subfolder for each mod. The Asset Toolkit is an example of a project that does this.