Git Guide

Making arma missions with the TMTM dev hub, and Git.

This guide is intended to provide an overview of the basic procedures for using Git with the TMTM dev hub for mission creation. Using Git (as well as the dev hub) provides many benefits for mission creation, including (but not limited to):

• Tracking of versions, and changes to the mission files
• Easier collaboration, including assistance provided by other mission makers
• Issue tracking, To-Do lists, and more

In order to use Git with the dev hub, you will require the following software on your computer:

• Git for Windows: https://git-scm.com/
• TortoiseGit (optional but highly recommended): https://tortoisegit.org/
• Notepad++ (optional but highly recommended): https://notepad-plus-plus.org/

This guide will cover the installation of Git for Windows, as well as TortoiseGit. It is possible to use Git entirely on the command line, however this guide will not cover that, and will instead focus on the use of TortoiseGit.

Installing Git for Windows

Once you have downloaded the Git for Windows installer, start the installation process as normal until you get to the "Select Components" page. You should make sure that "Git Bash Here" and "Git GUI Here" are both disabled, and that "Git LFS (Large File Support)" is enabled (see image for details).

On the "Default Editor" screen, it is recommended that you select Notepad++ (if you have it installed).

On the "PATH Environment" screen, ensure that you have "Git from the command line and also from 3rd-party software" selected. This is required in order for TortoiseGit to function at all.

For "Choose your SSH executable", you can leave it on the default "OpenSSH" option.

For "Choose HTTPS transport backend", select "Use the OpenSSL library".

On the "Line Ending Conversions" screen, ensure that you have "Checkout as-is, commit as-is" selected. Arma runs on windows, you will be making missions on windows. There's no reason to select any of the other options.

On the "Terminal Emulator" screen, leave it on the default of "MinTTY".

On the "Extra Options" screen, ensure that you have "File system caching" and "Git Credential Manager" enabled.

You should now be finished installing Git for Windows. Now we need to install TortoiseGit.

Installing TortoiseGit

TortoiseGit can be installed entirely on the default settings. However, make sure that you have the "Run first start wizard" box checked on the final screen.

Once the setup window opens, select your language, then hit "next".

The next window should automatically have picked up on the Git for Windows install path (usually something like C:\Program Files\Git\bin). If this field is blank, you may have to locate it manually (that can happen if you install TortoiseGit before Git for Windows).

On the "Configure user information" screen. Set your name to your username, and your email to the same email that you will use for the dev hub.

On the "Authentication and credential store" screen. Ensure that "TortoiseGitPlink" is used for SSH. Then click "finish".

SSH Key Setup

Now that you have Git for Windows, and TortoiseGit installed. You'll want to generate an SSH key to use with the dev hub (you can use git over HTTPS, but you'll have to enter your dev hub password every time). Open your start menu, and search for "PuTTYgen". It should come installed with TortoiseGit. Open it. You should see a largely blank window with a "Generate" button highlighted. Click the "Generate" button, then follow the instructions to generate your SSH private key.

You should now see your generated key. You can name it using the comment field if you want. Press the "Save private key" button (click "Yes" through the "Save without passphrase" window), and save the key file to a permanent location on your computer. You don't want to be moving this around once you've saved it, as TortoiseGit will need to be able to find the key in order to connect to the dev hub. My recommendation is an "SSH Keys" folder in your documents.

Under no circumstances should you send this private key file to anyone. The private key is used to authenticate yourself to the dev hub. If you sent it to someone, they might be able to edit your repositories!

With the PuTTYgen window still open, head over to the dev hub, and ensure that you're logged in.

Go to your user settings, then the "SSH Keys" page.

You should see a big blank text box, with a "Title" box below it. Take the contents of the "Public Key" box in PuTTYgen (the big box at the top), and copy them into the blank text box on the dev hub. Give your key a descriptive title ("My Desktop" or something, you're the only one who will ever see this) and hit "Add Key".

You should now have an SSH key added to your dev hub account. When you make changes to your mission, TortoiseGit will load the private key (that you saved on your computer), and then send the public key (which you pasted on the dev hub) to the dev hub. This allows the dev hub to confirm that it is in fact you making these changes to your missions.

Using the Dev Hub

The primary use of the dev hub is to store missions (and other TMTM development projects) using "Projects". A project contains a repository, an issue tracker, a wiki (if needed), and more.

To get started with your mission, go to the main page of the dev hub and click the "New Project" button.

Set a name for your repository. This should be a descriptive name for your mission, and can be changed at any time down the road (if you decide to rename it).

Leave the project URL as https://dev.tmtm.gg/*your_username_here*

Set the project slug to a short descriptive name for your mission. This can be changed, but should not be changed once created. (An example would be a mission name of "Daybreak 2 - Sunrise", and a slug of "daybreak-2")

Set the description to a brief description of your mission. This can be changed at any time.

Hit the "Create Project" button.

You should now have a brand new project for you to use. At this point, we're going to be looking for the "Clone" button in the top right corner. Clicking this button should expose two links, "Clone with SSH", and "Clone with HTTPS". Copy the "Clone with SSH" URL by pressing the button on the right side of the text box.

Navigate to your "Documents\Arma 3 Other Profiles\*A3 Profile Name*\MPmissions" folder. Right click on it, and you should see a TortoiseGit option for "Clone".

Once you open the clone dialog, it should automatically fill the URL with the one you copied earlier. If not, copy the URL again, and paste it into the URL field.

Check the box for "Load Putty Key", and navigate to the SSH key that you saved earlier.

Press the "OK" button to begin cloning.

TortoiseGit should clone the repository, and provide you with a warning that the repository is empty. That's fine, we haven't added anything to it yet.

In your MPMissions folder, you should now have a folder with the same name as the "Project Slug" you set on the dev hub. Rename this folder, and add the map to the folder name (ex. change "it-aint-me" to "it-aint-me.Tanoa").

Add your mission.sqm to this folder. If you have no started on the mission at all yet: open the Arma 3 editor, save a blank mission (with any name), and copy the mission.sqm to the new repository folder.

The folder should now have a little red circle icon on top of it. That indicates that you have changes that still need to be committed to the repository. Right click on the folder, and select "Commit".

This will open the Commit dialog. In the message box, state what you've changed. In this case, write something like "Initial commit" to indicate that you're just starting the repository.

In the "changes made" section, you can see all of the files that have changed. You should see your new mission.sqm listed here with a status of "Not versioned". Check the box beside it.

At the bottom of the window, click the drop-down beside the "Commit" button, and select "Commit and Push". This will commit your changes to your local copy, then push that to the dev hub.

Wait for the dialog windows to finish, you should see a "Success" message at the end.

If you go back to the dev hub at this point, you should see your mission.sqm in your repository!

General Git Workflow

The basic method to work with a git repository is as follows:

• Before you start work, use a "Pull" to update your local copy. This is more relevant when working with other mission makers, but it's a good practice to do regardless. This ensures that your local copy is the most up-to-date version from the dev hub.
• Make your changes to your mission. You should see red icons over any files/folders that have been changed.
• Once you finish a change (i.e. making loadouts), right click the mission folder and hit the "Commit" button again. Write down what you have changed (ex. Changed Rifleman magazine count from 6 to 8), and then hit the "Commit and Push" button to push your changes to the dev hub.

This process ensures that your local copy is up-to-date before you start work, and that your changes always get pushed back to the dev hub. If you see red icons, you should probably commit your changes!

Git is capable of many more advanced workflows than we have covered here, but this should cover the basics that you need to know in order to use git at all.