WowInterface.com has recently added support for git repositories for addon developers. This allows you to now choose between Git and SVN, using whichever version control system you are most comfortable with.

The Git system works in a very similar way to the SVN system that you may already be familiar with. You can create repositories for projects that already exist or you can even create a development repository for an unreleased addon, creating the actual addon project later on. You can push new files from the web interface, allowing you to easily package up new versions of your addon without any fuss or mess

Before you can begin using the Git system on WowInterface.com, you will need to supply an SSH key that enables authentication with our servers. If you aren't familiar with SSH or how to create or obtain a key, you might find the following guides useful:

• http://nathanj.github.com/gitguide/tour.html
• http://www.electrictoolbox.com/article/linux-unix-bsd/create-rsa-dsa-keys-ssh/

Once you've created your public and private key pairs, you will need to give your public key to WowInterface in order to allow the system to authenticate you. To do this, navigate to Git Control Panel and click the "Git Keys" button.

In the window that pops up you will see a place to add your key, with a spot for you to give it a name you can recognize in case you have multiple keys, and the text of the key itself. Please ensure when you are adding your key that you paste the public portion of your key, not the private portion. The public key should be stored in a file ending with the extension .pub. Here's an screenshot of me adding my home machine's public key:

Once you click the 'Add key' button, it will show up in the listing where you can delete it if necessary. You can always delete and re-add a key if something does not work properly.

Once you've added your key, you should be able to authenticate with the server, although this relies on your local machine being set up properly. You can always post on the forums if you are having difficulty, although SSH public key authentication can be a bit tricky to get working.

The next step, once your public key has been added to the system, is to create a repository. You can either create a repository manually (if an addon project does not already exist, or create one based on an existing project.

Each addon project which does not currently have a git repository will be listed after your list of existing repositories. To create a repository for one of these projects, simply select the checkbox and click the 'Auto create' button.

In order to manually create a new repository, scroll down the page and fill in that portion of the form, clicking 'Manually create' when done

Once you've done this, your repository will appear in the listing:

Once you've created a repository, you will need to clone in in order to do commit any development back to WowInterface. These instructions will be given for UNIX-based systems, although they should be a bit easier if you are using a graphical client for Git, such as on Windows. This guide assumes your public key is already established with your system and it will be used to attempt authentication with remote hosts.

Find your repository in the listing, and copy the address that is listed. This address will begin with [email protected] and will end with the specific id of your repository. For example:

Open your terminal window and run the following command:

git clone  

For example, if you'd like to clone the example repository above into the directory /home/cladhaire/addons/GitRepoExample then run the following:

git clone [email protected]:GitRepoExample-83 /home/cladhaire/addons/GitRepoExample

Cloning into GitRepoExample...
warning: You appear to have cloned an empty repository.

Obviously this command will need to altered for your specific needs, i.e. the repository you would like to clone and the destination directory. Once the repository has been cloned, you can begin making changed and committing files to the repository. Unlike SVN, Git allows you to make as many changes and commits as you would like without those being uploaded to the server. When you are done making changes and want to publish your changes, you will push them to the repository.

Pushing the first set of changes you've made to your repository is a bit different than pushing regularly, so this FAQ entry helps explain how to make your first push to the remove repository.

Using the example repository we've already used, we've created a file called GitRepoExample.toc with some basic text:

## Interface: 40000
## Title: GitRepoExample

GitRepoExample.lua

We've also added a GitRepoExample.lua file with the following:

print("GitRepoExample has been loaded")

Not a terribly useful addon, but sufficient for our example. Now we want to add these to the local repository on your machine. We use the git add command to accomplish this:

git add GitRepoExample.toc GitRepoExample.lua

This adds the two files to the staging area, allowing us to commit both of them at the same time. We commit them by using the git commit command.

git commit -m "Initial commit of base addon"

Depending on your setup, you can not specify the message in the commit and an editor will pop-up so that you can use multiple lines and have an easier time editing the message. For the purpose of this FAQ, we'll use the command-line arguments for brevity. Either way, the output of the commit looks like this:

[master (root-commit) b69e91a] Initial commit of base addon
 2 files changed, 5 insertions(+), 0 deletions(-)
 create mode 100644 GitRepoExample.lua
 create mode 100644 GitRepoExample.toc

You can see that the commit has happened by running the git log command, which might show the following:

commit b69e91a4b151c9a67773f0707eebb79a9d61e3fd
Author: James Whitehead II 
Date:   Thu Jan 13 12:19:45 2011 +0000

    Initial commit of base addon

Now, in order to push these changes to the remote repository, you will run the git push command. Specifically, you will type the following:

git push origin master:master

This command tells git to push your local set of changes to origin, which is the canonical name for the repository from which you cloned your local copy (if any), pushing the local master branch to the remote master branch. The branch name on the left side of the colon is the local branch, and the right side is the remote branch. This special syntax is needed in order to tell your local git client how to publish the changes you make locally. The output of the command is as follows:

Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 364 bytes, done.
Total 4 (delta 0), reused 0 (delta 0)
To [email protected]:GitRepoExample-83
 * [new branch]      master -> master

We can see that the new branch was created on the remote end of the repository, and any new repository cloned would contain this information. In the future when you want to push your commits to the repository, you can continue specifying the branch names, or you can simply omit them, using git push or git push origin by itself.

Although in your repository you may wish to create the addon structure yourself, for example creating a directory called GitRepoExample and then putting the .toc and .lua files underneath, but this is not required. By not doing this, you allow your repository to be checked out directly into your addons directory without any further fuss, but obviously zip files created will not work properly. You can rectify this by configuring the Git system on WowInterface to package your addon under a directory.

To configure this option, find your repository in the listing and select 'Options -> Miscellaneous' in the dropdown:

In the resulting addon page, you can use the 'Prefix Directory' field to specify the directory you would like your project to be packaged under. For the example we have used, you could specify GitRepoExample.

Make sure you click 'Update Options' to update the configuration for your project.

Now, when using our example repository and the prefix directory 'GitRepoExample', we can create a zip file and see the following output:

Of course this option can be changed at any time, and the next packaged zip will reflect the new set of options.

There are visibility options available for Git projects that allow you to configure whether there is any public access to your repository. There are three options, shown in the dropdown on the Miscellaneous Options screen:

There are three different types of access to project repositories:

• SSH Git Access: This is how you as a developer access your repository, and it is always enabled. You can configure fine-grained permissions using the 'Team Permissions' options dialog. but this method of access cannot be disabled.
• ViewGit access: All Git projects can be made available via the ViewGit web interface, allowing people to view your activity, subscribe to RSS feeds and even view the files in the repository. If you don't want your repository to be visible, you should disable this method of access.
• Git daemon access: This method provides read-only access to users who might not necessarily have SSH keys registered with WowInterface. This gives them a low-cost way of cloning your repository in order to follow development.

Using the configuration dialog you can allow full public access to your repository, disable the web viewer for your project, or disable all public access to the repository. As always you have full control over the visibility of your projects.

Just like its SVN cousin, Git integration on WowInterface allows you to have the packager automatically update the version number in your packaged files. The system is slightly different, matching the method used by WowAce and CurseForge, allowing you to push the same files to two different repositories and get automatic versioning on both sets of sites.

You can simply add @project-version@ anywhere in your .toc file and it will be automatically expanded to show the revision or tag name that was used to create the file. For example we can alter GitRepoExample.toc as follows:

## Interface: 40000
## Title: GitRepoExample
## Version: @project-version@

GitRepoExample.lua

Now, once we've committed and pushed this change to the repository, our next packaged file will have this tag replaced. For example, the following file is created when I package a new version:

## Interface: 40000
## Title: GitRepoExample
## Version: fb6aa1e

GitRepoExample.lua

Because I built this package using the HEAD revision, the packager simply replaced the version with the latest commit that the master branch of my repository currently points to. This version number is a unique revision id that can be used to tell git what specific commit is being referenced. Compare it to the git log:

commit fb6aa1e6f06860086b856bd1d26a72f7ca1f5736
Author: James Whitehead II 
Date:   Thu Jan 13 12:51:12 2011 +0000

    Adding versioning to table of contents

commit b69e91a4b151c9a67773f0707eebb79a9d61e3fd
Author: James Whitehead II 
Date:   Thu Jan 13 12:19:45 2011 +0000

    Initial commit of base addon

If you look closely, you can see that the first few characters of the most recent commit are exactly what was shown in the version field. This can allow you to identify what commit of a given addon your users are using when trying to debug problems. Of course this only works on files that have been packaged, so users that are using your addon directly from a cloned repository will have this show as @project-version@ still.

If you instead build your package from a tag, rather than from the HEAD revision, the tag will be displayed. For example, a recent version of Clique has the following version number listed in the .toc file:

## Interface: 40000
## Title: Clique
## Author: Cladhaire
## Version: v40000-1.3.3

This was generated by the packager, because I used the git tag 'v40000-1.3.3' to generate the file.