How to Use Subversion

We’ll describe here some of the basics about using subversion: starting out, changing things, and tagging releases.

This document is not a complete and robust explanation for using SVN, but more a quick primer to get started with plugins on WordPress.org. For more comprehensive documentation, see The SVN Book.

For additional information, please see these documents:

Terminology Terminology

If you’re new to subversion, you’ll need to know what a few words mean, so let’s go over how subversion behaves to introduce some terms.

All your files will be centrally stored in the svn repository on our servers. From that repository, anyone can check out a copy of your plugin files onto their local machine, but, as a plugin author, only you have tho authority to check in. That means you can make changes to the files, add new files, and delete files on your local machine and upload those changes back to the central server. It’s this process of checking in that updates both the files in the repository and also the information displayed in the WordPress.org Plugin Directory.

Subversion keeps track of all these changes so that you can go back and look at old versions or revisions later if you ever need to. In addition to remembering each individual revision, you can tell subversion to tag certain revisions of the repository for easy reference. Tags are great for labelling different releases of your plugin.

Top ↑

SVN Folders SVN Folders

The SVN repositories come with four folders:

/assets/
/branches/
/tags/
/trunk/

Even if you do your development work elsewhere (like a git repository), we recommend you keep the trunk folder up to date with your code for easy SVN compares.

Top ↑

How To … How To …

The following sections will walk you through some of the basics of SVN

Start your brand new plugin

All you need to do is add the plugin files you already have to your new SVN repository.

To do that you’ll need to first create a local directory on your machine to house a copy of the SVN repository:

$ mkdir my-local-dir

Next, check out the pre-built repository

$ svn co https://plugins.svn.wordpress.org/your-plugin-name my-local-dir
> A	my-local-dir/trunk
> A	my-local-dir/branches
> A	my-local-dir/tags
> Checked out revision 11325.

As you can see, subversion has added ( “A” for “add” ) all of the directories from the central SVN repository to your local copy.

To add your code, navigate into the my-local-dir folder: $ cd my-local-dir

Now you can add your files to the trunk/ directory of your local copy of the repository using copy/paste commands via command line, or dragging and dropping. Whatever you’re comfortable with.

Once your files are in the trunk folder, you must let subversion know you want to add those new files back into the central repository.

my-local-dir/$ svn add trunk/*
> A	trunk/my-plugin.php
> A	trunk/readme.txt

Warning: Do not put your main plugin file in a subfolder of trunk, like /trunk/my-plugin/my-plugin.php as that will break downloads. You may use subfolders for included files.

After you add all your files, you’ll check in the changes back to the central repository.

my-local-dir/$ svn ci -m 'Adding first version of my plugin'
> Adding trunk/my-plugin.php
> Adding trunk/readme.txt
> Transmitting file data .
> Committed revision 11326.

It’s required to include a commit message for all checkins.

If the commit fails because of ‘Access forbidden’ and you know you have commit access, add your username and password to the check-in command.

my-local-dir/$ svn ci -m 'Adding first version of my plugin' --username your_username --password your_password

Edit a file that is already in the repository

We’ll assume you’ve already got your plugin repository filled with the needed files. Now suppose you need to edit one of the files to improve the plugin.

First go into your your local copy of the repository and make sure it’s up to date

$ cd my-local-dir/
my-local-dir/$ svn up
> At revision 11326.

In the above example, we’re all up to date. If there had been changes in the central repository, they would have been downloaded and merged into your local copy.

Now you can edit the file that needs changing using whatever editor you prefer.

If you’re not using an SVN GUI tool (like SubVersion or Coda) you can still check and see what’s different between your local copy and the central repository after you make changes. First we check the status of the local copy:

my-local-dir/$ svn stat
> M	trunk/my-plugin.php

This tells us that our local trunk/my-plugin.php is different from the copy we downloaded from the central repository ( “M” for “modified” ).

Let’s see what exactly has changed in that file, so we can check it over and make sure things look right.

my-local-dir/$ svn diff
> * What comes out is essentially the result of a
  * standard `diff -u` between your local copy and the
  * original copy you downloaded.

If it all looks good then it’s time to check in those changes to the central repository.

my-local-dir/$ svn ci -m "fancy new feature: now you can foo *and* bar at the same time"
> Sending	trunk/my-plugin.php
> Transmitting file data .
> Committed revision 11327.

All done!

If the commit fails because of ‘Access forbidden’ and you know you have commit access, add your username and password to the check-in command.

my-local-dir/$ svn ci -m 'Adding first version of my plugin' --username your_username --password your_password

“Tag” a new version

Each time you make a formal release of your plugin, you should tag a copy of that release’s code. This lets your users easily grab the latest (or an older) version, it lets you keep track of changes more easily, and lets the WordPress.org Plugin Directory know what version of your plugin it should tell people to download.

First copy your code to a subdirectory in the tags/ directory. For the sake of the WordPress.org plugin browser, the new subdirectory should always look like a version number. 2.0.1.3 is good. Cool hotness tag is bad.

We want to use svn cp instead of the regular cp in order to take advantage of SVN’s features.

my-local-dir/$ svn cp trunk tags/2.0
> A tags/2.0

Now, as always, check in the changes.

my-local-dir/$ svn ci -m "tagging version 2.0"
> Adding         tags/2.0
> Adding         tags/2.0/my-plugin.php
> Adding         tags/2.0/readme.txt
> Committed revision 11328.

Alternately, you can use http URLs to copy, and save yourself bandwidth:

my-local-dir/$ svn cp https://plugins.svn.wordpress.org/your-plugin-name/trunk https://plugins.svn.wordpress.org/your-plugin-name/tags/2.0

Doing that will perform the copy remotely instead of copying everything locally and uploading. This can be beneficial if your plugin is larger.

After tagging a new version, remember to update the Stable Tag field in trunk/readme.txt!

Congratulations! You’ve updated your code!

Top ↑

See Also See Also