1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.
5/5, 1 rating

Managing a Shard's Code with Git

Summary of the tutorial

In this tutorial I will show you step-by-step with images how to use Git on Windows to manage a fork of ServUO for the following purposes:
  1. Extend ServUO to add custom content and behavioral changes
  2. Update ServUO to keep up with the latest developments while easily maintaining customization
  3. Retain the privacy of custom changes
  4. Share bug fixes with the ServUO team
Tags:

1 Introduction

To follow along with this tutorial, please download and install Git SCM from here: https://git-scm.com/download/win

A safe place to stash the code is also needed. As this tutorial assumes that privacy is important it will be using the free GitLab services at https://www.gitlab.com for private Git hosing. To follow along with this tutorial please sign up for an account there now. If another Git hosting solution is used the reader will need to fill in the gaps.

2 A Word about the GPL

ServUO is distributed under a software license. The dozens upon dozens of men and women that have contributed to ServUO and its predecessors over the years have done so with the condition that the terms of this license agreement be kept. When a person decides to alter the software in any way they are also agreeing to the terms of the license and are legally bound to abide by it. This should not be a scary thing. In fact it is quite straight forward. Let's explore what this means so we can be better educated.

ServUO is distributed under the terms of the GNU GPL v2. The full text of the license can be found in the file "LICENSE" inside the ServUO directory and online here: http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html . ServUO is distributed with a clause that allows others to distribute it under later versions of the GNU GPL license if they so choose.

What this license says in short is, if someone receives a binary copy of the program they are entitled to a fully copy of its source code. Furthermore it restricts an author from redistributing the program under a different license other than a later version of the GNU GPL.

How this is relevant to our tutorial: Should a shard owner keep all of their changes private, operate the server, and make the service available to players, they are in keeping with the terms of the license. They have not distributed the binary of the server to anyone that does not have the source because only they have a copy of the binary. If the shard owner decides to make their changes publicly available in source-code form they are also in keeping with the terms of the license. Everyone can get the source. The only way a shard owner can run afoul of the terms of the license is to distribute the modified version of the server in binary form only without providing some means of access to the source code.

3 Git BASH, your new friend

Throughout the rest of this tutorial we will be executing commands on the command line. The command line we will use is called "Git Bash". This is very different from the Windows command prompt. Bash is the standard command line interpreter for most Linux distributions and is required by Git to function correctly. The Git Bash command line also contains many standard Linux utilities like grep and find. These utilities can be extraordinarily useful for deep analysis of the project source code. They are outside the scope of this tutorial, however I recommend the reader to do further research.

Open a Git Bash window now. Do this by opening the folder where you would like your source code to live, for example the "Projects" directory on your desktop. Then right-click in the folder and select the "Git Bash Here" option. This is what it looks like:
Spoiler

upload_2016-4-15_11-0-10.png
upload_2016-4-15_11-2-24.png

For the remainder of the tutorial all commands and output will be in text form.

4 Creating the Project

Create a new empty git repository with the hosting provider. The hosting provider should provide a URL or git command suitable for cloning this new repository on the local machine. If using GitLab, this is what the process looks like:
Spoiler

upload_2016-4-15_9-19-44.png
upload_2016-4-15_9-20-0.png
upload_2016-4-15_9-20-11.png


In this example, my Git URL is https://gitlab.com/qbradq/MyShard.git . Some services use the .git extension, some do not. Copy this URL and use it to clone the repository on your local machine with the following commands.

Code (C#):
  1. git clone https://gitlab.com/qbradq/MyShard.git
  2. cd MyShard
Note that we have moved into the MyShard directory. From now on when a Git Bash shell is opened it should be within this directory.

Right now all git knows is that we have a project, it contains no files, and it is hosted on the Internet at GitLab. This host is called the "origin" in git. Because we want to get updates from ServUO we need to tell git that this project has a parent. The parent is called the "upstream" in git.

Code (C#):
  1. git remote add upstream https://github.com/ServUO/ServUO.git
Now git understands that this project has a parent that lives on the Internet at GitHub. Next we'll ask git to pull down everything in the parent project and merge it with what is currently in our project, which at this time is nothing.

Code (C#):
  1. git pull upstream master
This will take some time. Not only is it downloading all of the code for ServUO it is also downloading the entire history of everything that has ever changed in ServUO.

Finally we need to push all of this data up to our host. Until we push what has changed on our local computer the host doesn't know about it. And neither do the other developers if any, and the servers we want to deploy to.

Code (C#):
  1. git push
This will again take some time. Now we have our project set up and correctly configured to pull from ServUO as its parent project. More importantly we have saved all of this work to our host.[/code]

5 Creating the Shard

Content not yet filled