Creating a synchronized Github fork of a WordPress.org Subversion plugin repository

August 5, 2013

Big Notice!

If you are looking to sync only in one direction this tutorial is the one for you. After weeks of hitting my head on the wall due to constant conflicts I found out that the way git and svn store histories is very different and two way sync with this method simply does not work properly. To see how to make two way sync work for realsies check out my new post Creating a two way sync between a Github repository and Subversion

Carry on

WordPress.org utilizes Subversion for all plugins in the WordPress plugin repository. It may not always be ideal for your project to use Subversion. In some cases you may want to use Github to manage the development and only host the plugin in the WordPress.org repository. In this tutorial I will show you how to use the git-svn command to interact with a Subversion repository using Git.

Note that while this tutorial mentions the specifics of the WordPress.org Subversion plugin repository and Github for Git these instructions should be able to be applied to any Git-Subversion scenario.

Prerequisites

Update: git-svn is now built in to Mac OS X so you will likely not need this step.

In order to complete this tutorial you will need git-svn. If you are running Mac OS X you can get git-svn setup via ports with the following commands

$ sudo port uninstall git-core

$ sudo port install git-core +svn

( NOTE: git-svn is now git svn )

Setup the repository

In this setup we will check out the Subversion repository and at the same time initialize the local Git repository for ourself.

$ git svn clone -s http://plugins.svn.wordpress.org/jetpack

Be warned, this step can take quite a while if the repository is large. If you wish to start from a specific revision number use

$ git svn clone -s -rN:HEAD http://plugins.svn.wordpress.org/jetpack

Where N is the revision number to start from.

The -s signifies that the repository has the standard layout with trunk/, tags/, and branches/ folders. All plugins on WordPress.org should have this structure so it should be safe to use for our purposes.

Link to Github

Update: It is not really ideal to use a remote repo in the same branch as the svn remote. See updated tutorial at Creating a two way sync between a Github repository and Subversion

In order to link our new repository to Github we need to first visit Github and create a new repository for our plugin.

Now in the local repository your setup in the previous steps we need to setup the remote, which will be something like

$ git remote add origin git@github.com:blobaugh/Jetpack.git

To check that your remote has been setup run the following command:

$ git remote -v

And you should see output similar to

origin    git@github.com:blobaugh/Jetpack.git (fetch)
origin    git@github.com:blobaugh/Jetpack.git (push)

This shows that you have permissions to pull updates from and push updates to the linked Github repository

Start developing

Everything is setup for you to start developing this cool new features you have been wanting. Your master branch is linked with the Subversion repository on the WordPress.org plugin repo so I suggest you work out of a branch for new features, then merge that branch to master and push it back into the WordPress.org repo.

To see all the branches you currently have:

$ git branch -a

To create a new branch

$ git branch my_new_feature

To switch to that branch run the following. Make sure you switch to the branch or you will overwrite the code in the wrong branch!

$ git checkout my_new_feature

When you are satisfied and ready to merge the new code back into the master branch:

$ git checkout master
$ git merge my_new_feature

If you no longer need your new feature branch you can erase it with

$ git branch -d my_new_feature

Getting updates from Subversion

Update: If you only pull updates from svn and do not push back this method works great. If you need two way sync see Creating a two way sync between a Github repository and Subversion

If development work is still going on in the Subversion repository you will want to pull in any new updates before you attempt to push changes back in. Note that this is not an option, it is a requirement. Subversion will not allow new changes until you have pulled in any updates from the Subversion repository.

Make sure you have switched back to the master branch

$ git svn rebase

Handling conflicts

You will eventually run into a conflict with a merge from Subversion or another branch. Solve these conflicts the normal git way. If you are rebasing run the command again at the end just to make sure you have all the changes.

Committing code back to the WordPress.org repository

Update: If you are only using this to push back to the svn repository and not pulling from it it should work ok. If you need two way sync see Creating a two way sync between a Github repository and Subversion

So your new feature is complete and merged to master, you have pulled in and resolved any conflicts from Subversion. There is only one thing left to do, push back to the WordPress.org repository for all the world to enjoy the new functionality!

Make sure you have switched to the master branch

$ git svn dcommit

Make it go

If you want to automagically synchronize the Github and WordPress.org repositories you can now setup a script with a cron to run the rebase and dcommit commands.

This tutorial may be updated with a demo script for this at a later time.

Ben Lobaugh