Setting up an Online Repository

From Frictional Wiki
Jump to navigation Jump to search

This article describes the process of setting up an online Git repository, and discusses the workflow.

Why do I Need a Repository?

The biggest benefit is to combine changes made by all members of the mod team into a single "current" copy. If you're working on a mod by yourself, you probably don't need an online repository. However, an offline one will still give you many other benefits, which online repositories also provide. If you break something, you can easily compare to the previous version (or rollback to it), and easily keep track of exactly what things you've changed since the previous version. Also, if valve update the source code, a repository can make the task of merging the two versions of the code considerably easier.

Terminology

  • Commit - A snapshot of the project. Its purpose is to allow to revert unwanted changes and any accidents (such as deleting something). On the graph below, individual dots are commits.
  • Repository - The service 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.
  • Master Branch - The mutual version of the project; every now and then you (or the project manager) will need to merge your version with the "official" (master) one. This will create a new commit. However, before branches can be merged, you will need to push (upload) your changes to the online repository. You should also make it a habit to pull (download) from the master branch before starting any work. On the picture below you can see the master branch (blue), and a side branch (green, "Feature").
  • Tip - is the latest commit in a branch

To do: Add pic for demonstration

Getting Started

In this guide, the following applications and services are used:

  • Git
  • GitLab
  • GitKraken

First, it is necessary to install Git on our local machine and later set up the local and online repository.

  1. Download and install Git.
  2. First-time Git Setup - "Your Identity" is the important part of the article. This step is still optional, but will resolve headaches later.
  3. Register a free account at GitLab
  4. Before you can properly use the online git functions, you will need to generate an SSH key and add it to your gitlab account. Here's a guide.

Creating the Project


Cloning the Project

  1. Navigate to the directory in which you want to place the mod folder at.
  2. Inside the folder, right click and click on "Git bash here".
  3. Copy and paste the following command (right click because Ctrl+C doesn't work in Bash):
    git clone git@gitlab.com:MyRepository.git FolderName
    

Creating a Remove

This is an additional step to make the git workflow a little bit easier.

To make the process of downloading/uploading easier, a remote can be created; it's a shortcut which replaces the lengthy repository URL with a short acronym; generally speaking, a common name for a remote is origin, but it can be called in any name. The command is:

git remote add <remote_name> <remote_repo_url>

Usage example:

git remote add origin git@gitlab.com:MyRepository.git