Setting up an Online Repository

This article is about version control. It describes the process of setting up an online Git repository, and discusses the workflow.

The sole purpose of the article is to explain how to set a repository up and running. Check "See Also" in order to learn how to actually operate and maintain the repository.

Introduction

Version control

Version control is the process of maintaing a history of project versions which can be compared and reverted to, if anything goes wrong. A version control system basically gives you the ability to quickly create a back-up of your changes with a few clicks (this is called a "commit"). Because only the changes are recorded, this process if very quick. Loading a commit also loads all of the previous ones, so the project is always preserved in its entirety.

Changes to each file have to be added to a commit before one is created, so if something e.g. gets accidentally deleted, this change can be discarded and the file is restored (this is a much simpler and way faster process than restoring a regular back-up).

Why do I need an online repository?

A repository is what records all the changes in a project. Creating a repository ("repo" for short) basically means that you start to monitor changes in a project. It can be stored locally (the repo is essentially a hidden folder in your project folder), but it can also be uploaded online.

The biggest benefit of an online repo is the ability to easily combine changes made by all members of a mod team into a single "current" copy. It also allows team members to check out the versions of the project that other members are working on.

Another important benefit is having an off-site back-up of your project. If you permanently delete your project folder, the repo (which is stored inside the project folder) will be gone along with it. An online repo lets you get back all your work within minutes, if something like that happens.

If you're working on a mod by yourself, you probably don't need to put your repository online. However, for the reason stated above, it can be safer to have an online one.

Terminology

Git branches are useful to separate your version from the main project version, and later be merged when your work is done. The master branch is blue, and the side branch is green.

Commit	A snapshot of project changes. Its purpose is to allow to revert unwanted changes and any accidents. On the graph below, individual dots are commits.
Check out	Changing the current commit is called like this, i.e. "check out a commit".
Revert	This basically means "uncommiting" changes. It is also often used as a way of saying "check out an older commit (before smth was broken) and work from there".
Pull	"Download" commits from the branch in the repository. You pull in order to update the project on your end.
Push	"Upload" your local commits to the online repository. You push in order to update the project on the repository.
Repository	The data structure that stores each commit; it is often used as a substitute for the folder which holds the project.
Branch	A separate chain of commits; think of it as making your own version of the project, while others make their own ones. You can also have multiple branches made for different purposes. For example, it is advised to create a new branch when you want to test something that might break the project but can't be done in a single commit.
Merge	This means joining two branches. A branch is always merged into another branch (called the target), so only one ends up having all the changes in it. Merging creates a new commit in the target branch.
Master Branch	The main version of the project. It is customary to only put stable versions of the project in the master branch. A good practice is to create separate branches for work-in-progress commits and merge them into the master branch when the feature in question is finished.
Pull/Merge request	If you're not an admin on the repo, you won't have the permission to push to the master branch. To have your work merged into the master, you will need to push your branch to the online repo, and then request the merge. This is called a Merge Request on Gitlab and (a bit confusingly) Pull Request on Github.
Gitlab, Github	Both are online services that offer to store your repos. At base level they are almost identical, although github is more popular for open-source projects.

Getting Started

One of the easiest ways to setup an online repository is to use the following services:

• GitLab (online repo storage)
• GitKraken (a GUI for Git)

It is necessary to install GitKraken on our local machine and later set up the local and online repository.

1. Register a free account at GitLab
2. Download and install GitKraken Git GUI

The set-up process might seem long and complicated, but you only need to do it once and it will save you a lot of work once you start using version control.

Creating the Project on GitLab

1. In your dashboard, click the green New project button or use the plus icon in the navigation bar. This opens the New project page.
2. On the New project page, choose blank project.
3. On the Blank project tab, provide the following information:
   • The name of your project in the Project name field. When adding the name, the Project slug will auto populate. The slug is what the GitLab instance will use as the URL path to the project. If you want a different slug, input the project name first, then change the slug after.
   • The Project description (optional) field enables you to enter a description for your project’s dashboard, which will help others understand what your project is about. Though it’s not required, it’s a good idea to fill this in.
   • Changing the Visibility Level modifies the project’s viewing and access rights for users.
   • (Optional) Selecting the Initialize repository with a README option creates a README file so that the Git repository is initialized, has a default branch, and can be cloned.
4. Click Create project.

Usually, you may want to initialize your project with a README file, but if you already have an existing mod folder you want to push to git, do not initialize your project with a README file. Save the project and follow the instructions inside for pushing an existing folder.

Setting up GitKraken

1. Open GitKraken.
2. Go to File->Preferences->Authentication.
3. Select GitLab and click on Connect to GitLab.
4. Approve the connection.
5. It is recommended to generate an SSH key and add it to your GitLab account. Here's a guide.

Cloning the Project using GitKraken

1. Open a new tab if there isn't one open already, and click on Clone a Repo and then GitLab
2. In Where to clone to, navigate to the directory in which you want to place the mod folder at.
3. Select the Repository to clone and click on Clone the repo!
4. Wait until the files are copied. When it's done, a prompt will show up to open the repo in the app - click on it to open the repository window.
5. You can now create branches, commit, pull and push your changes via GitKraken!

HPL Engine-Specifics

When it comes to modding with the HPL engine, the following files should be added to the .gitignore list:

• *.map_cache
• *.preload_cache

The files on the gitignore list won't show up in your changes list between commits, making it much less cluttered.

See Also

Git Tutorial: Command-line Fundamentals

GitKraken Tutorial For Beginners