Git Tutorial

This is a tutorial for using git to contribute to the More Events Mod; it's one of the two ways to submit work to our mod. If you prefer to use the command line, want a more streamlined workflow, or are interested in a significantly larger repertoire of features than is available through GitHub Desktop, then directly using git is for you.

Also note that git is the original program github was designed to work with. It has a much fuller feature set and it is much easier to find help through google searches (or talking to other team members) for any problems you encounter.

This is a rather minimal introduction, intended to get you the basics to use git for our project as quickly as possible. Git is a very popular piece of version control software, and if you want to learn more than project-specific basics, I recommend reading this book, particularly chapters 1 and 2.

#GitHub Account If you do not already have a GitHub account, create one at https://github.com/join. Once you have a GitHub account set up, you may want to try the GitHub tutorial, which will get you started in git as well: https://guides.github.com/activities/hello-world/

#Installation If you previously used GitHub Desktop, then git is already installed. Otherwise, download and install git. If you need them, instructions are available here.

To avoid odd crashes, you will need to specify a text editor, and notepad doesn't really work for this purpose. If you don't already have a preferred advanced text editor, I recommend installing Notepad++.

#Command Line You will need to use git on the command line. On a Windows computer, this means you need to add the path to the git binary file (for me this is C:\Program Files (x86)\Git\bin) to the environment variable named PATH (if you don't know how to do this, google [your windows edition] change PATH environment variable). I believe (but am not 100% certain) that git will be immediately available from the command line on a Linux or Mac system. From here on, when I tell you to enter a command, I mean into the command line.

#First Time Setup There are three things you definitely want to set up when using git. The first two are your name and your email address, which will appear on GitHub as you enter them here:

git config --global user.name "Your Name"
git config --global user.email [email protected]

You also should specify a default text editor, as failing to do so can sometimes cause weird crashes. If you have nothing else, use notepad, but if you have a more advanced text editor like notepad++ go with that instead. The example below is the path I use on my computer.

git config --global core.editor "'C:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -nosession"

The extra flags after the path are important, but vary based by editor; I'm not sure what they are for non-Notepad++ editors (if you know, add it to the wiki!)

#Connecting a Remote Repository (You can skip this step if you've already set up GitHub Desktop.)

Navigate in the command line to the folder you want to install the More_Events_Mod project files in (I recommend .../Paradox Interactive/Stellaris/mod for ease of in-game testing). If you already have a More_Events_Mod folder in this location, you will need to move it somewhere else (unless it already exists because you created it in GitHub Desktop or with a git clone command or equivalent -- in which case you can skip this whole step). Now enter git clone https://github.com/MoreEventsMod/More_Events_Mod_Beta/.

Now you should be properly set up. To confirm this, type

git status

The output should read

On branch master
nothing to commit, working directory clean

(The branch might have a different name.)

#Setting origin To make it easier to submit work to our project, I recommend entering

git remote add origin https://github.com/MoreEventsMod/More_Events_Mod_Beta.git

which will give the name origin to the main project repository on GitHub.

#Checking Out a Branch to Work On Before you make changes or additions to the code, you need to tell which version of the code you want to modify. To do this, you checkout the appropriate branch. The command to do this is

git checkout [branchname]

If you are adding a new feature, you should start from the master branch, so enter the command git checkout master. If you are modifying a feature, you should start with that feature's branch (which may be specific to the feature or may be the dev branch -- feel free to ask in chat if you're uncertain).

If it has been a while since you cloned the repository, you should update to the latest version of the branch (otherwise you will just get the version that existed when you cloned the repository). To do this, type

git pull origin [branchname]

At this point you are ready to make your changes using whatever program you like. When you are ready to save your work in git, continue with the next step of the tutorial (Note: If you are adding or changing more than one feature, you should come back to git, commit your work, and check out a new branch between features. Do not edit more than one feature per commit!)

#Committing Your Work (saving it in git) When you are ready to save changes you have made in git, type

git commit -a -m "[description]"

where [description] is a short (one line of max 72 characters) summary of what you have changed. This summary is mandatory.

You can confirm that this worked correctly by typing git status, which should say that there is "nothing to commit, working directory clean". You can also use git status at any time to see if you have committed all your current work to git -- if so, you'll get the same message, if not, you'll get a list of files that differ from the current commit.

(If you want to add a longer summary of what you have changed, you can instead use the command git commit -a. This will open up the core text editor that you selected earlier. Put a short (one line) summary on the first line, leave an empty line below it, and then write as many additional comments about your commit as you want. Once you're done, save this file and close your editor. Git will then commit your changes with the longer message in addition to your short summary.)

#Branches If you want to make a new branch for your project, type

git checkout -b [branchname]

where [branchname] is what you want the branch to be called (no spaces).

If you want to switch branches, type

git checkout [branchname]

where [branchname] is the existing branch you want to switch to. You can see a list of branch names by entering

git branch

Note that you cannot switch branches if you have made changes that you have not yet committed to git (except by using git stash, which is too advanced for this tutorial).

#Pushing Your Work (publishing it to GitHub) If you want to publish your work to GitHub so that other members of the project can use it, you will need to use the push command. To do this, type

git push origin [branchname]

where [branchname] is the name of the branch you want to publish.

#Pulling (getting newer versions of the project) If you want to get a more recent version of our project (i.e., if someone else has made changes and you want them on your computer), you will need to pull from GitHub. To do this, first commit your current work, then type

git checkout [branchname]

where [branchname] is the branch you want to update. Then type

git pull origin [branchname]

This will download the latest version of our mod and merge it with your current work. It is possible this will lead to a merge conflict. If that happens, I recommend asking for help in discord; in the meantime, you can cancel the pull by entering

git merge --abort

Warning: You should not pull if you have uncommitted changes.

#Merging (combining branches) When discussing pulling, I mentioned that it merges the update with your current work. This merging is a primary feature of git. It will attempt to intelligently combine the files from the update with the files you have worked on to produce files containing both sets of features. Usually it's quite good at this, but sometimes it fails, in which case you get merge conflicts. These have to be resolved by manually editing the files with conflicts to combine the two versions. To see which files have conflicts, type "git status". You can abort an in-progress merge that has conflicts with git merge --abort

You can also merge your own branches even without pulling. For example, perhaps you want to test several features you changed at the same time. To do this, you will first create a new branch that will contain the code you want to test. For this example, I will name the branch my-test-branch. First, checkout the branch of one of the features to be tested, say `feature-1':

git checkout feature-1

With this branch checked out, create your new branch:

git checkout -b my-test-branch

(remember that the -b creates a new branch). While you still have my-test-branch checked out, merge in the other feature branches you want to test:

git merge feature-2
git merge yet-another-feature

This will make the branch my-test-branch contain all the changes from feature-1, feature-2, and yet-another-feature.

#Admins If you are an admin, or if you have push access to the main repository's master, stable, and beta branches for any other reason, there are some additional commands you may find helpful.