How to Use Subversion

We’ll describe here some of the basics about using subversion: starting out, changing things, and tagging releases. For more comprehensive documentation, see The SVN Book.

First, some 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 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.

Words are great, but how do I actually use the darn thing?

Let’s describe a few basic tasks you might want to accomplish.

Task 1: Starting from scratch with your brand new plugin repository

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

To do that you’ll need to

1. Check out the blank repository.
2. Add your files to the trunk/ directory of your local copy of the repository.
3. Check in those files back to the central repository.

# Create a local directory on your machine to house
# a copy of the repository.

$ mkdir my-local-dir

# Check out the 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 repository to
# your local copy.

# Copy the plugin files to the local copy.
# Put everything in the trunk/ directory for now.

$ cd my-local-dir/
my-local-dir/$ cp ~/my-plugin.php trunk/my-plugin.php
my-local-dir/$ cp ~/readme.txt trunk/readme.txt

# 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

# Now check in the changes back to the central repository.
# Give a message to the check in.

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.

# All done!

Task 2: Editing a file that is already in the repository

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

To do that you’ll need to

1. Make sure your copy of the repository is up to date.
2. Edit the file.
3. Double check your changes.
4. Check in your changes.

# cd into 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.

# Good: all up to date. If there had been changes in the
# central repository, they would have been downloaded and
# merged into your local copy.

# Edit the file that needs changing. I use nano.
# No need for editor wars; use whatever you like.

my-local-dir/$ nano trunk/my-plugin.php
# ... edit ... edit ... make typo ... edit
# ... fix typo ... edit ... all done.

# You can check and see what's different between your
# local copy and the central repository.
# 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.

# Looks good. Let's 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!

Task 3: “Tagging” 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.

To do that you’ll need to remember to update the Stable Tag field in trunk/readme.txt beforehand!

Then you’ll

1. 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.
2. Check in that new subdirectory.

# You've just checked in the latest and greatest updates
# to your plugin, let's tag it with a version number, 2.0.
# To do that, copy the files from your trunk/ directory to
# a new directory in tags/.
# Make sure to use `svn cp` instead of the regular `cp`.

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.

# All done!