Development:Working With Git

Git is a distributed revision control and source code management system.

GitHub and GitLab are web-based hosting service for projects that use the Git revision control system.

Together, these two tools allow developers working on The Mana World to easily collaborate and merge changes into the game.

Installing Git

To install Git, select the appropriate Operating System at Git Downloads and follow the instructions. (For Windows users, accept all the default settings for the installer.)

• Please note that although the download for Windows includes a GUI tool, we will focus on the Git Bash command line tool in order to maintain consistency across platforms.

After installation, please follow the basic setup instructions at GitHub under the Set Up Git heading.

You will likely also want to set up SSH authentication for GitHub. This can be done by following their SSH Guide.

Preparing To Use Git

Creating a Fork

Once you have installed Git, your first task should be to create a personal copy (also known as a fork) of the server data on your GitLab account. This will allow you to make changes and save them to a place where the content leaders can retrieve copies to include in the main server. It's also easier to work with.

To create a fork, login to your GitLab account and go to the TMW Repository.

• You will see a button on the page that says Fork. Click it.
• You should now see a page that has some details and history for the fork you just created. At the top will be a series of buttons including one that says SSH. Clicking the SSH button will create a link for you to copy which will be needed in the next step. It will look like https://git.themanaworld.org/yournamehere/serverdata.git. Copy that link or keep the page open; we'll need it later.

If you will be working with client-data or music, you will need to create separate forks for those repositories as well.

• client-data
• music

Keep in mind you'll need more tools to run a localhost, see appropriate pages regarding that.

Creating a Clone

You now need to create a copy of the data on your computer to work with (also known as a clone). We will create a clone from the main repository and set up Git to allow you to push changes to your personal fork.

If you are using Windows, open the Git Bash tool which you installed earlier.

If you are using Linux, open a terminal window.

• Navigate to the folder where you want to create your clone.
• Now issue the command to have Git create a copy: git clone --recursive https://git.themanaworld.org/evolved/serverdata.git serverdata
  • The --recursive command tells Git to copy all of the data from the included submodules (client-data and music). If you don't plan on working with these, it can be omitted.
  • Currently, only TMWA has these as submodules, so it can also be omitted.
  • The serverdata at the end of the command is the name of the folder you want the data in. In the example, git clone --recursive https://git.themanaworld.org/evolved/serverdata.git serverdata will create a new folder called serverdata and put the files inside that folder. You can use any folder name that makes sense to you.

Note that copying the data may take some time.

After the data is finished cloning to your computer, you need to tell it how to keep track of changes.

Creating Remotes

When a repo (short for repository) is cloned, it has a default remote called origin that points to the repo it was cloned from. To allow you to make changes on your personal fork, you need to add another remote which we will name fork.

• Change to the directory you created when you cloned your repo: cd serverdata
• Using the link we found at the end of the Creating a Fork section, issue the command git remote add fork https://git.themanaworld.org/yournamehere/serverdata.git

We'll also need to add remote pointers and select the correct branch for the submodules, if you cloned them. This currently only applies to tmwa servers.

• cd client-data
• git remote add client-data https://git.themanaworld.org/yournamehere/clientdata.git
• git checkout master
• cd music
• git remote add music https://git.themanaworld.org/yournamehere/tmw-music.git
• git checkout master

Git includes the ability to work with branches, or multiple versions of files. This can provide a way to work on separate projects without having to create a new clone for each one. We won't be going too deeply into this option, but the option is there once you are more comfortable. By default, you will be working on the master branch. The command above, git checkout master, tells the submodule which branch you want to use.

At this point you now have a personal fork, a local clone, and remote pointers for your fork. You're ready to start making changes! You are free to use whatever tools work for you to make your changes, but please ensure that the final results are in harmony with The Mana World's formatting guidelines. There's TmwAthena Scripting Standards and Evol2 Scripting Standards (the later based on Linux Kernel Convention).

Day-to-day Use

Retrieving Changes

Because many developers are working on the project at the same time, you will want to make sure you have all the latest changes before making a commit. This will ensure that your changes do not conflict with changes another developer has made.

If you have not made any changes yet and want to make sure your clone is up-to-date before starting to work, you can simply pull from the repo.

• git pull

If you have made local changes and want to get the latest updates before continuing, you will need to tell Git to get the updates and then apply your changes on top of them.

• git pull --rebase

Making Commits

After making changes to any of the source files (maps, graphics, scripts) you will want to save those changes so other developers can see and review them. You need to commit those changes to Git. When committing files to Git, you will need to have a terminal or Git Bash open in the directory containing the changes. For example, if you are changing music files, you will need to be in the TMW/clientdata/music folder.

Your first step toward making a commit is to verify that Git recognizes there have been changes.

• git status

You will receive a result that tells you what branch you are working on, what files (if any) have been modified, and what files (if any) are untracked. At this point, we want to add our changed or untracked files to Git.

• Issue the command git add <file> replacing <file> with the path and filename of the file to be added. Be careful: the commands ARE case sensitive!
• Repeat as needed until your changed files are all added.
• Issue the command git commit -m 'your message here'
  • Using the -m switch in the command allows you to specify a brief commit message which will tell others what the changes are.
  • For example, git commit -m 'Spelling corrections for Beer quest' will tell others that we made corrections that might apply to multiple files, without giving an overload of detail. If you aren't sure how much detail to include in a commit message, you can check with the development team on IRC for suggestions.

Pushing to a Fork

Once you have committed your changes to your local clone, you now have to put them where they can be seen: your fork. To ensure that your fork will match what you have in your local clone, we will tell Git to force the changes to the repo.

• git push -f fork master
  • Please note that using the -f option to force your changes causes Git to overwrite commit history on the repo. This option should only ever be used on personal forks to bring them into the same state as the main repo.

If you have been working on and committing changes to music or client-data, you will need to push those to their respective forks.

• git push -f client-data master
• git push -f music master