Version control all the things

Version control is practically essential to any software project, and it can be extremely useful even for your Minecraft server. What it does is simple: track any change, either large or small, knowing exactly who made the change, when the change was made, and exactly what the changes were. Software projects tend to use them because of those benefits, but if you aren’t already, there are many benefits to tracking every plugin, mod, or configuration change made to your server.

  • Easily spread around the work of updating the server (or corresponding client) with others. No more figuring out how to merge changes when you need to send files to other team members. Compared to Dropbox, you have far more tools available to you with a proper version control system — easily see differences down to individual lines.
  • Track every “release” of your server, which means that you can know exactly what was updated on what day, and most importantly, allow you to rollback to a prior release without having to scrounge around for the old files or old configurations.
  • If combined with a “deployment script,” you can just plug in a version that you want (i.e. release-2013-02-20) and your server could be automatically updated. Did the update go badly? Return to an old version (release-2013-02-16 perhaps?) instantly.

When we need to update the server (or client, in the case of a modded server), it’s just a matter of a few commands. It is almost a luxury to do updates (well, at least until you realize mod X eats all the bandwidth and plugin Y has a dupe exploit you missed).

Picking a version control system


The most remarkable difference between version control systems (VCS) is whether one is “distributed” or not.

  • With a non-distributed VCS, a central server stores all of the history and each person with access has a copy of the latest version. Changes made must be immediately sent to the server when “committed” (at least historically; some systems have updated to be more competitive with distributed systems).
  • A distributed VCS does not require a central server to store the entire repository. Each person has an entire copy with all of the history, and each person can make changes independently, and multiple commits can be collected together before they are pushed to a central server. Distributed VCS software still allows for collaboration, but the server hosting the repository is not particularly special: it merely has the copy that everyone else synchronizes with.

I personally strongly recommend Git, a popular distributed VCS used for WorldEdit, Bukkit, and many other projects. It has good support for non-text files too, which is perfect when you need to store binary code (.jars and such).

Now that I’ve chosen Git for you

You need to get Git. For Linux users, you can get it from your operating system’s package manager. Windows users should install mysysgit (I recommend selecting “Use from command line” during install), but they should also consider installing TortoiseGit too, which allows right clicking folders in Windows Explorer and using Git with an actual GUI. Mac OS X users can get an installer and can also get a GUI too.

Furthermore, if you are working with others or wish to later “deploy” the changes to a server from that server itself (if you have a VPS or dedicated server), you may want to host a version of your repositories somewhere. It provides a central place for several people to synchronize changes with. Many services provide public open source repositories for free, but you probably are considering a private option.

  • GitHub is arguably the most popular Git service provider. They charge for the number of repositories that you have, but allow for an unlimited number of collaborators, with a micro plan starting at $7/mo (as of writing).
  • BitBucket charges by the number of collaborators, but allows for an unlimited number of repositories. They also have a free plan as well, which you may want to start out with.
  • You can also set up Git on your own server if you have one. Linux users can setup Gitolite.
  • There are also many other services that provide Git hosting, which you can look for. Assembla is another one.

How Git authenticates you is not through a password: you need to generate an SSH key, which is kind of like a super long cryptographically-generated password (but a bit more than that). You can generate a key using ssh-key-gen on Mac OS X or Linux, or with PuTTYgen on Windows. Two keys will be generated: a public one to give to the host that you may have chosen (GitHub, BitBulcet, etc.), and a private one you need to keep secret and that you will use to authenticate yourself.

Using Git

One minor downside to Git is its higher learning curve, but the effort will pay off. Let’s first review some of the words that you will have to know to start, some of which are common to all version control systems.

  • The log is your log of changes.
  • A commit is a set of changes that you make together and then apply a description to (i.e. “Fixed X and Y”).
  • A branch is a “fork” of your repository, which a separate list of changes that can diverge from the main branch.
  • A merge is the merging of changes from a different branch (to the top of the current branch’s list of changes).
  • A conflict is when automatic merging fails because two people modified the same file at the same place.
  • Pushing is sending changes to a server.
  • Pulling or fetching is receiving the latest changes from a server.
  • A clone is the process of downloading the entire copy of a repository.

Sadly, a full-blown tutorial for using Git is a bit outside the scope of this article, but Git has a wonderfully large number of resources. You can start by using this interactive Git tutorial and continue on by reading this Git book. Linux (and Mac OS X) users can also try this step by step introduction. If none of that fancies you, you can try searching the web, or possibly asking a few of your programmer friends :)

Be aware that Git is predominately a command line program, but if you had installed a GUI, you can try using that. The processes and terminology carry over; you just know need to press the right buttons!

On the subject of a deployment script, it is much easier if you control the server that Minecraft is hosted on. That way, you can simply download the latest changes from Git and copy them over to where the server’s files are stored. Otherwise, you may have to use something to upload the files over FTP. Sadly I do not have an example deployment script to provide, as mine is fairly specific to my case, but all you need to do (which you can even put as lines in a .bat file) is download the latest changes using the right git commands (i.e. git pull, or git checkout release-XXXXX) and then copy files as needed (or compile plugins, or whatever).

  • QuestionMark

    Great idea to use Git for Minecraft. I have recently discovered a lot of potential uses for Git. I am now using Git for my Latex documents, source code and as a backup of /etc on my Linux box. I simply symlinked the .git directory to an external drive!
    Another good software for hosting Git on Linux is Gitlab. Gitlab has a very Github-like interface (actually looks even better) and is constantly updated and maintained.

    Funny thing; The Git source is hosted on Git!

    • sk89q

      Ooh, I didn’t know about GitLab. I’ll have to check it out sometime.

    • Mentioum

      Yeah I’ve used GitLab on a couple of Unity3D projects :) It’s nice

  • Mentioum

    Have you used fabric before? It’s awesome for pulling in git repositories remotely without actually having to access the server in question :).

    Well its actually awesome for running any remote commands :)

  • Circuitbomb

    Bitbucket’s free plan lets you create private repositories as well, which can be nice if your working small with a few people. Github’s Windows client is quite nice if your not on a *nix box and does support working with repositories that aren’t through their specific service.

    Gitlab is new to me, so thanks for mentioning it; I’ll check it out.

  • Silthus

    Nice Article :)
    I have already been using GIT + Gitlab and a custom deployment script for some while now and it is working quite beautiful.
    Our deployment process is so that we checkout the plugin folder locally and test stuff there then push it and deploy it in a simple web interface by selecting the branch (representing different server) and clicking a button.
    This also automagically posts a changelog to forum containing all commits from the last server push to now.

    If anyone is interested I can provide the deplyoment scripts used.

  • Daniel Hodgson

    Not surprised to see this. I came up with the same idea back in 2011 when I realized how much time and effort I was putting in to keeping track of bukkit versions, plugins, their configurations, and especially permissions configurations. This is definitely great advice.

    Personally my friends and I use Gitorious hosted on our colo server. We also push all our open source stuff to our GitHub organization.

  • tjbenator

    When using git on a Minecraft server, would you have it ignore certain files such as sqlite files or flat files that store user information?

    • sk89q

      I keep files that are modified by the running server out of Git and separately backup those (using something like rsnaphot). I do that for my websites too.

      What I keep in my Git are things that a human intentionally changes.