My last post on using Git with wordpress.org/extend is one of the more popular resources on the web on the subject. But since writing it, I’ve changed my workflow a bit more. So, instead of writing a new guide, I added an addendum to the old one. Enjoy!
Some months ago, I wrote about using Git and Github with the wordpress.org plugin repository. Since that time, I’ve been refining my plugin development workflow. I now do all of my development with Git, using git-svn tools to do all svn management.
Preamble: Git as primary vs secondary
Before talking more about my workflow, I should make a sort of conceptual distinction. When I develop most of my plugins, I am working alone. In these cases, Git is primary. It’s where the meaningful version control happens, while svn.wp-plugins.org is just a gateway for wordpress.org/extend, the distribution channel. I am not using the wordpress.org svn repository for version control or code sharing in any interesting way. Likewise with a few team projects that I’m involved in, notably Anthologize. All of our code-sharing and true version control happens via Git and Github (here’s our repo), with the wordpress.org svn repo used only as a distribution mechanism.
In contrast, I also use Git to develop BuddyPress, but the strategy is quite different. In the case of BuddyPress (as in the case of WordPress), the svn repo is the officially sanctioned version control system for the project. Git, in this case, is a secondary, local versioning system – essentially, my development sandbox. This setup places additional restrictions on how the git-svn link is managed, raising issues such as juggling svn branches, tagging version off of an svn branch, exporting patches in an svn-compatible format, and so on.
In this post, I’ll be focusing on the first kind of development setup, in which the wordpress.org svn repo is serving merely as a distribution channel. It’s a bit simpler to start there. Moreover, I’ve been chatting with Mark Jaquith about Git for WP development, and I know from those chats that he’s planning on writing up a description of the second kind of workflow (which characterizes the WordPress core work that he’s more concerned with). So I’ll leave the sophisticated stuff to him.
Part One: Getting your repos set up
You’ll need to have Git installed on your computer, with git-svn compiled. Here’s a guide to compiling it yourself on OS X; it’s also available through a number of repos on various OSes.
Create a directory for the plugin in the plugins directory of your dev install. I’ll use my recently released plugin Unconfirmed as an example; you can follow along using the example (until it comes time to push and commit!), or use your own plugin.
cd wp-content/plugins mkdir unconfirmed
The next step will require you to clone your wordpress.org svn repo. This assumes that you have requested and been granted space in the repository already. If you’re just starting plugin development and don’t want to request space yet, that’s OK – just begin your development in a normal Git repository. As long as you are pushing your Git changes somewhere (like Github), you’ll be able to wipe out your local copy when it comes time to send it to wordpress.org and start from this point as if you were starting from scratch.
Get a revision number for the plugin. You don’t want to force git-svn to crawl through the 300,000+ revisions on the wordpress.org repository. (For those keeping score, this is the only time you will have to run an svn-native command!)
svn log http://plugins.svn.wordpress.org/unconfirmed
Look for the first commit number, where the plugin was added to the repository. In my case, it’s r387893.
r387893 | plugin-master | 2011-05-23 04:10:19 -0400 (Mon, 23 May 2011) | 1 line adding unconfirmed by boonebgorges
Clone the svn repository into the local plugin directory. Here’s the syntax, followed by some explanation.
git svn clone -t tags -b branches -T trunk -r387893 http://plugins.svn.wordpress.org/unconfirmed unconfirmed
git svn cloneis the command itself
-t tags -b branches -T trunktells Git about the directory structure of the svn repository that you’re cloning. The flag
-sis shorthand for the same thing, though I’ve had mixed luck getting it to work – so I just enter the whole thing explicitly.
-r387893is the svn revision number where I want Git to clone. In the next step, we’re going to tell Git to fetch the svn revision history starting with this commit; that’s why we chose the first, rather than the last, commit from the unconfirmed repo.
http://plugins.svn.wordpress.org/unconfirmedis the address of the plugin on the wordpress.org repo. It’s important to use this address rather than the alias http://svn.wp-plugins.org. As I discovered (after much frustration), Git is not able to trace the branch/tag history from the wp-plugins.org address – you have to use plugins.svn.wordpress.org.
unconfirmedis the relative path to the directory where I want the repo cloned.
Next, fetch the svn commit history like so:
cd unconfirmed git svn fetch
When you hit enter, git-svn queries the wordpress.org repo, starting with the initial revision number you pegged in the previous step, and walks all the way forward to the (entire) repo’s most recent revision, mirroring your plugin’s svn revision history in your local Git clone. If you’ve just received the space in the svn repo, this will only take a few seconds. If you’re doing this with a plugin that was put into the repo some time ago, or one that has a lot of revisions (and branches and tags) in the svn repo, you’ll have to wait a long time. Drink a beer or ten while you wait.
You’ll know the process is done when you are returned to your command prompt. Test to make sure that you’ve pulled in all of the remote tree by entering the following:
git branch -r
This will show you a list of all the remote branches being tracked by this Git repository. If it’s a fresh repo, you’ll only see the trunk. If it’s a repo with existing branch and tag history, you’ll see one Git branch corresponding to the trunk, one corresponding to each svn tag, and one corresponding to each svn branch.
If you’re not planning to use Github or to share your code with anyone else, you’re done. If you are planning to use Github (as I do), you’ll need to add your Github endpoint as a remote repository. Assuming you’ve already created a repo on Github,
git remote add origin email@example.com:boonebgorges/unconfirmed.git
origin is the name I’ve chosed for the Github endpoint, but you can call it whatever you want.
Now it’s time to reconcile your commit histories. Hopefully, you’ve only got one history to deal with – either in the Git or in the svn repo – so you won’t have too much trouble. In such a situation, something like the following should work:
git pull --rebase origin master
So, here’s the thing about
--rebase. It rolls back, albeit temporarily, all of the changes on your local copy of the repository back to the last common commit, applies all of the remote revisions, and then attempts to apply your revisions on top of it. If you are working with a fresh Github repository, there will be no common commit in the history, and there won’t be any revisions from Git to rebase back onto the tree. Thus, the svn history will be rolled back, zero commits will be put onto the local repo, and the svn history will be laid back down. In other words, nothing will happen, except that the Github repository will establish a common ancestor revision, allowing you to push. Mutatis mutandis, if you have an active Github repo but an empty svn repo, zero commits will be rolled back, and your Github history laid on top of the local repo, with the zero commits laid back on top. In other words, it’ll sync with the Github history seamlessly, and allow you to commit back to the svn repo by establishing a common revision history. If you have active, separate commit histories in both svn and Github, may God have mercy on your soul.
In any case, use
--rebase with great caution. Read the git-rebase docs and try to wrap your head around it before doing anything that will mess up the revision history.
Once you’ve successfully pulled from Github, your three repositories – the local Git repo, the Github Git repo, and the svn repo on wordpress.org – will all be aware of each other and in sync. You are ready to develop.
Part Two: Day to day development
Let’s say you’ve found a bug (OH NOES) and you need to fix it. Before digging into the code, get yourself to the command line to make sure you’re in good working condition.
The first thing I do before I touch any code is to see what’s happening in my local repo:
There’s a lot of good information that
git status can give you, for which I refer you to the docs or to Google. The important concept for our purposes is that we start a new local branch every time we want to fix a bug or develop a new feature. The notion of hyper-specific, temporary branches is one of Git’s biggest selling points, as well as one of the places where it differs the most from the way that many WP developers work with svn. Since branches are strictly local unless explicity pushed, and since Git’s merge and rebase tools are so nice, you can create, merge, and destroy branches at will, and keep your work separate. To add (and switch to) a branch called stupidbugfix, use this syntax:
git checkout -b stupidbugfix
This does two things: it creates the new branch stupidbugfix, and it checks out that branch (similar to svn switch).
git status will show you that you are now
On branch stupidbugfix.
Do your bugfixing as you would normally do. When you’re ready to commit the changes, do another
git status. You might see a result that looks like this:
# On branch stupidbugfix # Changed but not updated: # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # # modified: readme.txt # no changes added to commit (use "git add" and/or "git commit -a")
In this case, I’ve made changes to one file: readme.txt. In order to commit these changes, you’ll first need to stage the file with
git add readme.txt
git add is automatically recursive, so you can add whole directories this way too.) Now you can commit the changes:
git commit -m "Fixing that stupid bug."
If you’re confident that you want to stage all changed files to a commit, you can skip the explicit
git add and use the
git commit -am "Fixing that stupid bug"
Now, let’s get your changes from the stupidbugfix branch into the master branch, which we’ll use to push to our central repository. Then we’ll delete the temporary stupidbugfix branch.
git checkout master git merge stupidbugfix git branch -d stupidbugfix
If you are sharing your code on Github, you can push your commits at this point:
git push origin master
Part Three: Releasing a new version to the wordpress.org repo
If you’re following the steps I’ve outlined above, all of your development is happening in Git and Github. The only time you’ll need to touch the wordpress.org repository is when you want to release a new version. Here is the procedure I use. [EDIT 2012-09-14: See the Addendum below for an improved workflow for this step.] First, rebase the svn trunk to your current branch.
git rebase trunk
This small bit is crucial, and it took me many months of frustration before I finally stumbled upon this (cache only!) blog post, which put me on the right track. The concept here – so far as I understand it, at least – is that git-svn actually rewrites the MD5 hash that Git uses to identify the changeset, and when you rebase the trunk into your current local branch, you forcing git-svn to match Git-changeset MD5s with svn-changeset MD5s. If you don’t do this, you’ll get infinite merge conflicts.
Now, let’s send those commits to wordpress.org svn.
git svn dcommit
This sends all changesets (since the last time you dcommitted) up to the WordPress svn repository. (In other words, you’re mirroring the revision history.) Once this is done, the revision history on your svn trunk will match that of your current git branch.
Now we’re ready to tag the release in svn. (I’m assuming that you’ve already changed current version and stable tag numbers in your plugin files before dcommitting. If not, make those changes, git commit them, git rebase trunk, and git svn dcommit.)
git svn tag 1.1
This will do the same thing as when you svn cp your trunk into tags/1.1.
I like to keep tag history in Git as well. Git tags are metadata (while svn tags are really just branches), so they have to be created separately, and pushed up to Github.
git tag -a 1.1 -m "Tagging 1.1" git push --tags
Finally, before making any more changes that can be pushed back to Github, you’ll have to rebase from Github – again, to make sure that Git understands that your Git MD5s have been overwritten by git-svn. Assuming you’re on your master branch:
git pull --rebase origin master git push origin master
Again, this rebase business is scary and dangerous, so try to understand the possible ramifications if you are working on projects that involve other people.
This might seem like a lot to learn. But developing in Git is hugely beneficial, well worth the learning curve. Git’s agile branching allows a kind of focused, compartmentalized development strategy that can’t easily be replicated with svn. And having Github as a bugtracker and changeset-viewer is also really great. Plus, working with Git in my own development means that I don’t have to code-switch (pardon the pun) when working with clients who use Git for collaborative work, which, I’m finding, is increasingly common. Learning about Git with your own WP plugins is a great way to learn some of the finer points of Git.
Addendum (14 Sep 2012): Be a better wordpress.org citizen and squash
The biggest headache in the git/wordpress.org workflow has always been lining up the revision histories. Git revision histories are non-linear, and SVN does not understand them. So the process of rebasing the development branch into the trunk-tracking branch is always precarious, as
trunk is a flattened, svn-friendly branch. Moreover, even when the rebase does work, you end up reduplicating revision histories in both Git and SVN, when the real purpose of wordpress.org SVN here is really just distribution. (This makes Otto sad.)
So, for the last six months or so, I’ve used a modified version of the release workflow described in Part Three. First, I have a local branch, which I call
svn, which tracks trunk:
git checkout -b svn trunk
At release time, I check out the
svn branch, and do a squash merge. This means that all changes since the last commit to the
svn branch are laid on top of
svn as if they were a single set of changes. You can then commit these changes as a single changeset (thus keepin’ it linear, and keepin’ it short for Otto’s sake):
git checkout svn # if you're not already on it git merge --squash master git commit -m "Merging changes from Git for 1.1 release"
Note that you might get a message from Git that there were merge conflicts, in which case you’ll need to use mergetool to clean up. But this is a subject for another post.
Then, do your
git svn dcommit and
git svn tag from the
svn branch. It’s important that you never rebase to or from the
svn branch, or do any development there; all changes on that branch should be squash-merged from a git-only dev branch.
A few quick thoughts about the Google Summer of Code Mentor Summit, which I attended last weekend.
Google Summer of Code is a program, run by Google, which encourages open source development by paying college students to undertake summer coding projects with various open source projects. I co-mentored two projects for WordPress, and was one of the lucky few from among WP’s fifteenish mentors to get a trip to the Googleplex in Mountain View.
The Summit was organized as an unconference. On Saturday, attendees proposed session topics on a big scheduling board, and indicated their interest in other suggested sessions with stickers. This being a supremely geeky conference, I didn’t understand about half of the session titles.
A few takeaways, in no particular order:
- Process matters. A lot. Probably 2/3 of the sessions I attended were devoted to project workflow: version control, code review, various kinds of testing. Probably some of the focus on process is due to the fact that it constitutes common ground between even those individuals whose software projects are quite different from each other. But I think it also speaks to the importance of workflow that really works, especially in the decidedly non-top-down world of open-source development communities.
- WordPress seems pretty far behind the curve in terms of development infrastructure. Take version control: WordPress is the only project I heard about all weekend that still uses (or is not in the process of moving away from) centralized version control like Subversion. Git seemed like the most popular platform (there was a whole session on migrating massive project repos from SVN to Git, which was probably my favorite session of the weekend). I came away with lots of ideas for how the WP and BuddyPress development processes might be improved (and, more importantly, why it might be worthwhile to pursue these ideas), which I’ll be working on in the upcoming weeks and months.
- More generally, I came away realizing that WordPress devs (and probably other kinds of devs, but this is what I know!) have a lot to learn from the way that similar software development projects are run. I was part of some extremely interesting conversations with core developers from Drupal and TYPO3 and was really, really impressed with the way the way that their development workflow informs and enables better software. Some WordPress fans have a tendency (sometimes joking, sometimes not) to disparage other projects like this, an attitude that can prevent us from learning a lot from each other. That’s a real shame, and it’s something I’d like to rail against.
Like this tutorial? Check out my updated and more comprehensive Git/Github/wordpress.org tutorial at http://teleogistic.net/2011/05/revisiting-git-github-and-the-wordpress-org-plugin-repository/.
I’m on a never-ending quest to come up with a good local environment that will support the kind of WordPress plugin development that I enjoy So Very Much. I’ve only just recently begun using Github for version control and already I can’t imagine living without it. But doing WP plugin development in Github is not totally straightforward, because wordpress.org’s plugin repository uses SVN. When it comes time to release a new version on the wordpress.org repo, it’s simply not practical to merge changes manually and manage two different version histories. I wanted a setup where I could use Github for everyday development, but would connect to WP SVN when I was ready to release.
There are lots of posts out there on how to use git-svn:
- Stas figured it out for BuddyPress Courseware
- Nicolas Kuttler on Using git for WordPress development
- Evgeni Golov on using plugins.svn.wordpress.org with Git
I couldn’t get any of the methods to work the way I wanted. But by mashing a few of them together, I have what is, I think, a workable setup. Here are the steps.
- If you don’t already have one, create a Github repository for your work. I’ll assume here that you have configured Git on your machine, with git-svn installed as well.
- Create a directory for your working copy. I use several local WP installations for plugin development, the main one of which is named Doris. So I’d do the following, for an imaginary plugin I’ll call awesome-plugin:
cd /sites/doris/wp-content/plugins mkdir awesome-plugin
- Before connecting to WP SVN, it’s a good idea to check for the revision number of your most recent commit. If you don’t, git-svn will sift through all 280,000+ revisions on svn.wp-plugins.org.
svn log http://svn.wp-plugins.org/awesome-plugin
Scroll to find the most recent reversion number. Let’s say that in this case it’s r287228.
- Clone the svn repository to your newly created directory. Because I want this working copy to actually work as a WordPress plugin, I’m not going to check out the entire awesome-plugin tree. Instead, I’ll just get the trunk, and when I want to tag new versions of the plugin, I’ll do it in a separate working copy on my machine. (This is perhaps not the ideal way to work, but for me it works – probably irrationally, I like having “clean” instances of the trees somewhere on my machine that are used only for tagging new versions.)
git svn clone http://svn.wp-plugins.org/awesome-plugin/trunk awesome-plugin -r287228
git svn clone will create the git-svn link and then do the initial fetch into the awesome-plugin directory.
- Depending on how you’re planning to use Git, you might want to create a branch that tracks the svn trunk, just for stable svn releases:
cd awesome-plugin git checkout -b svn remotes/git-svn
- Now that we’ve connected Git to WP SVN, we can connect to Github:
git remote add -f origin firstname.lastname@example.org:boonebgorges/awesome-plugin.git
I’m calling Github ‘origin’ because I’m so used to push and pulling to and from ‘origin’, but you can call it whatever you want. Of course, make sure to change ‘boonebgorges/awesome-plugin.git’ to reflect your username and repo name.
- Let’s test the connections. If your Github repo is empty, you can push stuff up right away:
git push origin svn
Remember that I am working on a branch called ‘svn’; you might use ‘master’ or something else altogether if you’d prefer. If your Github repo already had some files in it, you might find that you have to pull and merge them before pushing. Now make a change to your local:
touch test.txt nano test.txt # Type something in the document and save it git add . git commit -m "testing git-svn" git push origin svn
- Finally, let’s test to make sure that we can commit to SVN.
git svn dcommit
The first time you try this, you will be prompted for your wordpress.org password. If your local username is not the same as your wordpress.org username (mine isn’t), just hit enter and SVN will ask for your full creds. You should get a “Committing to…” message, followed by “Committed r123456” or something along those lines. You can check to see that your commit has gone through by visiting http://svn.wp-plugins.org/awesome-plugin/trunk in your browser.