From The Mana World

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

GitHub is a 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 on Windows, follow the step-by-step instructions found at GitHub.

  • 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.

To install Git on Linux, refer to the package installation method for your distribution.

Example: for Ubuntu distributions, a command would be issued in a terminal window: sudo apt-get install git

Setting Up Git

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 GitHub 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 GitHub 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 git@github.com:yournamehere/tmwa-server-data.git. Copy that link.

You now need to create a copy of the data on your computer to work with (also known as a clone).

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, replacing the example with the link you copied earlier: git clone --recursive git@github.com:yournamehere/tmwa-server-data.git TMW
    • 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.
    • The TMW at the end of the command is the name of the folder you want the data in. In the example, git clone --recursive git@github.com:yournamehere/tmwa-server-data.git TMW will create a new folder called TMW 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.

When a repo (short for repository) is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repo it was forked from. To keep track of the original repo, you need to add another remote which we will name mainline.

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 we do need to tell Git to use the correct branch.

  • Issue the command git checkout master

We'll also need to add remote pointers and choose the branch for the submodules, if you cloned them.

At this point you now have a personal fork, a local clone, and that clone is configured to work on the correct branch. 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. (Link needed)

Day-to-day Use

After making changes to any of the source files (maps, graphics, scripts) you will want to save those changes so others 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/client-data/music folder.

Your first step toward making a commit is to verify that Git recognizes there have been changes. This is done by issuing the command git status at the command line. 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.