Difference between revisions of "Setting up an Online Repository"

From Frictional Wiki
Jump to navigation Jump to search
(Rewrite)
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{wip}}
+
This article is about '''version control'''. It describes the process of setting up an online Git repository, and discusses the workflow.
  
This article describes the process of setting up an online Git repository, and discusses the workflow.
+
{{Note|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.'''}}<br>
  
==Why do I Need a Repository?==
+
==Introduction==
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.
+
===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.
  
==Terminology==
+
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.
  
*<u>Commit</u> - 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.
+
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.
*<u>Repository</u> - The service that stores each commit; it is often used as a substitute for the folder which holds the project.
 
*<u>Branch</u> - A separate chain of commits; think of it as making your own version of the project, while others make their own ones.
 
*<u>Master Branch</u> - 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").
 
*<u>Tip</u> - is the latest commit in a branch
 
*<u>Pull</u> - "Download" commits from the branch in the repository. You pull in order to update the project on your end.
 
*<u>Push</u> - "Upload" your local commits to th repository. You push in order to update the project on the repository.  
 
  
{{Todo|Add pic for demonstration}}
+
==Terminology==
 +
[[File:Git-branch-demonstration.png|alt=|thumb|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.]]
 +
{| class="wikitable"
 +
|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==
 
==Getting Started==
In this guide, the following applications and services are used:
+
One of the easiest ways to setup an online repository is to use the following services:
  
*Git
+
*GitLab (online repo storage)
*GitLab
+
*GitKraken (a GUI for Git)
*GitKraken
 
  
First, it is necessary to install Git on our local machine and later set up the local and online repository.
+
It is necessary to install GitKraken on our local machine and later set up the local and online repository.
  
#[https://git-scm.com/ Download and install Git].
 
#[https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup First-time Git Setup] - '''"Your Identity"''' is the important part of the article. This step is still optional, but will resolve headaches later.
 
 
#[https://gitlab.com/ Register a free account at GitLab]
 
#[https://gitlab.com/ Register a free account at GitLab]
#Before you can properly use the online git functions, you will need to generate an SSH key and add it to your gitlab account. [https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key Here's a guide].
+
#[https://www.gitkraken.com/ Download and install GitKraken Git GUI]
  
==Creating the Project==
+
{{note| 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==
  
 
#In your dashboard, click the green '''New project''' button or use the plus icon in the navigation bar. This opens the '''New project''' page.
 
#In your dashboard, click the green '''New project''' button or use the plus icon in the navigation bar. This opens the '''New project''' page.
 
#On the New project page, choose '''blank project.'''
 
#On the New project page, choose '''blank project.'''
#On th '''Blank project''' tab, provide the following information:
+
#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 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.
 
#*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.
Line 43: Line 79:
 
#Click '''Create project.'''
 
#Click '''Create project.'''
 
{{note|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'''.}}
 
{{note|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==
 +
 +
#Open GitKraken.
 +
#Go to '''File->Preferences->Authentication'''.
 +
#Select '''GitLab''' and click on '''Connect to GitLab'''.
 +
#Approve the connection.
 +
#It is recommended to generate an SSH key and add it to your GitLab account. [https://www.youtube.com/watch?v=z7jVOenqFYk Here's a guide].
 +
 +
==Cloning the Project using GitKraken==
 +
 +
#Open a new tab if there isn't one open already, and click on '''Clone a Repo''' and then '''GitLab'''
 +
#In '''Where to clone to, n'''avigate to the directory in which you want to place the mod folder at.
 +
#Select the '''Repository to clone''' and click on '''Clone the repo!'''
 +
#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.
 +
#You can now create branches, commit, pull and push your changes via GitKraken!
  
==Cloning the Project==
+
==HPL Engine-Specifics==
 +
When it comes to modding with the HPL engine, the following files should be added to the [https://git-scm.com/docs/gitignore .gitignore] list:
  
#Navigate to the directory in which you want to place the mod folder at.
+
*<code>*.map_cache</code>
#Inside the folder, right click and click on "Git bash here".
+
*<code>*.preload_cache</code>
#Copy and paste the following command (right click because Ctrl+C doesn't work in Bash):<syntaxhighlight lang="bash">
 
git clone git@gitlab.com:MyRepository.git FolderName
 
</syntaxhighlight>
 
  
==Creating a Remote==
+
The files on the gitignore list won't show up in your changes list between commits, making it much less cluttered.
This is an additional step to make the git workflow a little bit easier.
+
==See Also==
 +
[https://www.youtube.com/watch?v=HVsySz-h9r4 Git Tutorial: Command-line Fundamentals]
  
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:<syntaxhighlight lang="bash">
+
[https://www.youtube.com/watch?v=ub9GfRziCtU GitKraken Tutorial For Beginners]
git remote add <remote_name> <remote_repo_url>
 
</syntaxhighlight>Usage example:<syntaxhighlight lang="bash">
 
git remote add origin git@gitlab.com:MyRepository.git
 
</syntaxhighlight>
 
 
[[Category:Modding]]
 
[[Category:Modding]]

Latest revision as of 14:56, 11 April 2021

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

Note icon.png 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
Note icon.png 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.
Note icon.png 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