Creating a Git Repo for your Mod

Once you have started working on a mod of your own, you should set up a git repository for your mod.

This page will begin by explaining why you should use git, provide links to resources that explain basic git concepts, then provide a tutorial on how to use git in the context of Satisfactory Modding.

This tutorial assumes you have already followed the Getting Started guides for creating a simple mod and that you want to take your existing mod and place it into a git repository.

If you’re already an experienced Git user you can skip to this section.

Why Use a Git Repo

Advantages:

  • Easily return to a past version of the code to test functionality

  • Keep track of changes to write patch notes for a release

  • Easily share your source code with others

  • Backs up your files in case they get corrupted or you lose access to your computer

  • Makes it harder to misplace your files if returning to modding after an extended break

  • Version control usage is an important skill that can benefit any coder

Disadvantages:

  • One more tool to learn

Understanding Git

It is important to understand the distinction between "Git" and platforms like "GitHub" and "GitLab".

Git is open-source software created to manage files, usually text-based, by keeping track of what changes between distinct 'revisions' of the files. You can learn more about it here.

Git is traditionally accessed via the command line, but there are many different tools that offer a more approachable and convenient interface to the same functionality.

GitHub are GitLab are web platforms that allow you to store a git "repository" online, called a "remote", making it easy to collaborate with others, and providing a backup.

You should have already created an account on GitHub in order to obtain a copy of the custom engine version.

Git tools are used on your local computer to manage files. The files are then "pushed" (uploaded) to a git remote hosted by a platform like GitHub.

Git Tutorial on Gitkraken

Check out the first 4 tutorials at this link, namely:

This guide will walk through what you have to do for Satisfactory mods in specific, building off of this knowledge. We suggest you do not try to start putting your mod into a repo as part of watching these tutorials, but feel free to experiment with other folders on your computer.

You are, of course, free to check out other tutorials, but they cover topics less relevant to Satisfactory modding.

Beginner Git Users

You are free to use git from the command line, but it is recommended to use a GUI tool, as they are generally more approachable.

Consider the following software:

  • Github Desktop, free and great for beginners

  • Sourcetree, free but a bit more complicated than GitHub Desktop

  • GitKraken, free for non-commercial use as long as your code is public to the internet

  • Fork, free evaluation copy

This tutorial will use GitHub Desktop, but all are valid choices. There are additional directions below for GitHub Desktop setup. If you’re using another client, proceed to this section after completing its setup.

GitHub Desktop Setup

Follow the link above to download the GitHub Desktop installer. Once the file has downloaded, run it and sign in with your existing GitHub account.

Once sign in is complete, you will be presented with a "Let’s get started!" screen. If you’d like, you can create a tutorial repository, but for now, you should leave this program alone and continue with the steps below.

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.

Unsorted Notes

Unreal Engine may offer to turn on version control integration, but you probably don’t want this because it happens at the project level, whereas each of your mods is its own separate plugin repo.

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.

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.

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.