In this article we'll be giving a brief overview of how to setup and use the Git Source Control Plugin included with GameMaker. Before going any further, you should have a Git account already, and we recommend that you have a minimum working knowledge of how Git works and is used.

Setting Up

Note: We have made a large change to Git Source Control in 2.3.3, instructions for setting up in this version is given after this section.

Version 2.3.3 and later

In GameMaker 2.3.3 we changed the way that you will setup with source control. You are now able to interact with any command-line toolset you wish for GIT. This simplifies the setup in GameMaker considerably.

GameMaker will attempt to locate an installation of GIT on your machine, but you can supply your preferred command-line exe in the Git Executable Path box.

The Merge and Diff tool settings continue to work as they did in the past but the options are now passed along to the command-line tool of your choosing. You should check with the tools own help documentation to see the format in which they expect Merge and Diff options to arrive.

Project Setup

These settings will now be used to communicate with the repository when handling clone, push and pull requests. However, you still need to set up the per-project options which can be done by opening up the Main Options > General and clicking the Enable Source Control option. This will activate SCM for the current project.

Once you have enabled source control (and applied it or closed the Game Options) a new context menu will appear at the top of the IDE with the following option (which we'll explore in the rest of the sections of this page):

Repository Options

Standard Workflow

As you work on your project, you will naturally create sprites, edit scripts, delete timelines, and whatever else is required as your project develops over time. These are all actions which you may want to keep track of and get back should something go wrong. This is the main reason to use Source Control - so that any accidents can be reverted - and we will quickly take you through the basic workflow from start so you understand how this works.

Starting from the beginning, create a new GML project and then activate source control through the main options. This gives us access to the Source Control menu on the top, so we'll immediately go and Create Project Repository. If you look at the room resources, you can see that the default room has gained a red exclamation , meaning that it has been modified from it's last state. If we had other resources in the project, you'd see that they all have the same icon as shown in the image below:

We now have the option of either committing the blank project as it is, or getting it to a base state. For now, we'll do our first commit so click Source Control > Commit Changes. We'll now get a window split into three areas:

• Staged Changes - This represents the changes which will be committed to source. This will likely be blank, but it may show a Main Options change, which is fine.
  
  
• Unstaged Changes - This shows the files that have changed, but that we haven't told Git that we want to commit them - they're "pending" changes.
  
  
• Commit Message - This is a note that we can add to explain what the changes are.

For now, click the Stage All button, as we want to commit all the changes, and type something like "First Commit!" into the Commit Message and click Commit. All our resources should now have a green tick , meaning there's no modifications found.

It is worth noting that as you work within this window, the various Staged and Unstaged messages will be prefixed by a symbol. The symbol being used will vary depending on the operation and file, with the following possibilities:

• [...] - Staged Change (was previously [A])
• [+] - Newly Added
• [->] - Renamed/Moved
• [-] - Removed
• [M] - Unstaged Changes
• [?] - Untracked File
• [!] - Missing File

Our work process can now begin, and we can start to build our project and save and commit changes, just as we've done in the paragraphs above.

After working for a while, you may want to check and see what you've committed at any given time, and so for that you'll want to open the Commit History. To open the history window you simply go to Source Control > View History which opens another window with three panes:

The top pane describes the commits, the middle pane describes the comment given to the selected commit, and the bottom pane describes the files that have been modified in this commit. Note that if you have set up a Diff Tool, then double-clicking on any file in this window will open the diff tool and you'll be able to see the changes between the files.

After you commit your local copy, the next thing you need to do is Pull from the server (using the "Pull" option from the Source Control Menu). This will check for any un-synced changes. If there are no common changes GameMaker will use the recent version of each file, and you can Commit again the new version with all your changes in it, and then select from the Source Control menu to Push it to the server.

The complications start when you change a file that has already been changed on the server, which creates Merge Conflicts. When this happens, a window will pop up with all the conflicting files and 3 options:

• Use Theirs: This option replaces the local file with the one on the repository.
  
  
• Use Mine: Same as above, but you pick your local file as the one to keep, which will replace the one on the repository.
  
  
• Merge: Selecting this option opens both files using your merge tool. Sometimes the solution is trivial, other times you need to do a lot more work. I can't explain how to solve every merge conflict situation in this post, but I will go through a few in the next section.

After you resolve all the merge conflicts, you are free to Commit again and then use the Push option.

NOTE: When you pull, you may get a message alerting you that some files changed, and ask you if you want to reload them. This can get annoying. There's a setting in File > Preferences > General Settings called "Automatically reload changed files". Turn it on if you want to skip this dialog box in the future.

Version 2.3.2 and Earlier

Note: Due to changes on Github and other repository services the methods listed in this section may no longer function and you will need to update to GameMaker 2.3.3 / 2022+.

First of all, you need to setup an identity for Git to commit as, which means we need to go to the Plugins - Source Control (Git) section of the Preferences and add your authentication details:

This authentication identity will be used for all future projects, and GameMaker gives you two different ways that you can set it up:

• Username And Password: Clicking the "Add New User/Pass Authentication" button will present you with the following window where you can input the Repository URL, the Username and the Password:
  
  If you want this to affect just a specific repository then place the URL for the repository in the top field. However, if it's domain wide authentication you want (ie: "bitbucket.org" or "github.com" ) then just place the domain and nothing else. When something needs to check for authentication, it will look for a specific repository match first, and then a domain match. This will allow you to have a default authentication for a domain, and override with specific details for certain repositories later.

NOTE: If you are using an external repository, then you should be using the username and password associated with the account set up for that repository, but if you are wanting to use a local repository then you can use any username and password.

• SSH Keypairs: Clicking the "Add New SSH Keypair Authentication" will present you with the following window where you can input the Repository URL and Password before giving the paths to the Public Key and Private Key files required:
  
  Like the Username/Password authentications, you can have domain and repository specific authentications when using SSH keypairs. If you already have an SSH Keypair generated, you can set the paths up here, as well as any password required to access them. Note that should you need quick access to the public key, the copy button will automatically copy the contents to the clipboard for you. If you don't already have an SSH Keypair, clicking on the Create KeyPair button will bring up a file dialog of where to place the private key, and the public key will be created adjacent to it - this will fill out the paths to the public and private keys automatically for you.
  
  

NOTE for 2.3.2: If you need to edit the authentication details again, just double click on the entry and the details window will open for you to edit, but you will not be able to rename the URL. If you need to change the URL then you will need to delete the authentication details and re-add. To delete the authentication details, click on the close button on the left of the row in the main Preferences window.

You can find all this information plus extra tips on things like setting up a merge or diff tool or cloning repositories form the Source Control section of the GameMaker manual.