Adding your WordPress Plugin to GitHub

I’ve started putting my plugins on Github so it’s easier for developers to contribute. One of the big benefits of version control is the history, so I would hate to lose that on the move to git. The good news? I didn’t have to. The better news? It was actually easier than you might think. The instructions below are for GitHub but could easily be adapted to any git repo.

Start by setting up svn2git. You need to have git-svn, ruby, and rubygems istalled to use it:

sudo apt-get install git-core git-svn ruby rubygems

Then you can install the svn2git ruby gem:

sudo gem install svn2git

Now create your new repo on Github, but make sure to create an empty repo. Do not check the “Initialize this repository with a README” checkbox, and do not have it set up a .gitignore file or a license file. If the repo isn’t empty, the import process will not work.

GitHub New Repo

Now clone your new repo to your local system, and don’t worry about the warning that the repo is empty:

$ git clone git@github.com:{username}/{repository-name}.git
Cloning into '{repository-name}'...
warning: You appear to have cloned an empty repository.
Checking connectivity... done

Now you need to create an authors.txt file so that the users that committed to your plugin get proper credit in the Github repo. You can get the list of authors using this command, making sure to fill in the correct location of your WordPress.org plugin repository:

svn log --quiet  http://plugins.svn.wordpress.org/{your-plugin} | grep -E "r[0-9]+ \| .+ \|" | awk '{print $3}' | sort | uniq > ~/authors.txt

You’ll get a file that looks something like this:

aaroncampbell
plugin-master

If you see “plugin-master” in there, that’s the account that created your WordPress.org repo. I usually just credit that to myself. Now you need to modify that authors.txt file, setting a Github account for each username. You can set the github account E-Mail as well as the display name. The format should look like this:

aaroncampbell = Aaron D. Campbell <aaron@example.com>
plugin-master = Aaron D. Campbell <aaron@example.com>

Now that you’ve updated and saved the authors.txt file, you can use it in the next step. Start by changing to the directory you cloned the Github repo into. Now for the magic. There are two options, one is simpler and takes longer to run, one is faster and more complex. Read both and choose which makes sense for you:

The simple option is to run this svn2git command, making sure to fill in the correct location of your WordPress.org plugin repository and the authors.txt file you created:

svn2git http://plugins.svn.wordpress.org/{your-plugin} --authors ~/authors.txt --no-minimize-url

This command will take quite a while. The WordPress.org repository is quite large and it takes a long time to process that much history. The good news is, if you’re willing to take a couple extra steps, you can speed this process up a lot. We can do this by giving svn2git a subset of revisions to check. Start by running this command:

svn log --limit 1 -r 1:HEAD http://plugins.svn.wordpress.org/{your-plugin}

The item listed there should have a revision number like r41107, which was when your plugin was started. Run this command to similarly find the most recent revision for your plugin:

svn log --limit 1 -r HEAD:1 http://plugins.svn.wordpress.org/{your-plugin}

Now you can plug those into the command below, using just the numbers and dropping the leading r, and run the same magic but in a fraction of the time:

svn2git http://plugins.svn.wordpress.org/{your-plugin} --authors ~/authors.txt --no-minimize-url --revision {oldest-revision}:{newest-revision}

Once that runs, everything has been imported and committed, and all you need to do is push it to up to Github. Make sure to push the tags as well:

git push
git push --tags

That’s it! Your WordPress plugin, along with all it’s history, is now on Github.

Aaron On WordPress